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PREFACE 


Intercomm is a state-of-the-art teleprocessing monitor system of 
SDA, operating under the control of IBM 360/370 Operating Systems (MFT, 
MVT, VS). Intercomm monitors the transmission of mes- sages from 
terminals, concurrent message processing, centralized access to I/0 
files, and the routine utility operations of editing input mes- sages 
and formatting output messages, as required. 


This document provides a general introduction to and a detailed 
specification for use of the Intercomm System Utilities. The Edit and 
Output Utilities provide both terminal and format independence to an 
application program (message processing subsystem) executing under 
Intercomm control. The Change/Display Utilities provide predefined 
transactions for entry at a terminal to perform file inquiry and file 
Maintenance. The utilities are generalized; each installation codes 
tables using Intercomm macros to specify the precise use of the utility 
for their applications. 


This document is intended for both system and application pro- 
grammers. The following prerequisite Intercomm publications support 
the material contained herein: 

® Concepts and Facilities 

@ COBOL Programmers Guide 

@ PL/1 Programmers Guide 

@® Assembler Language Programmers Guide 

A User Review Form is included at the back of this manual. We 


welcome recommendations, suggestions and reactions to this or any 
Intercomm publication. 
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Introduction 


The INTERCOMM System Utilities (EDIT, OUTPUT, CHANGE/DISPLAY) 
are optional system components provided to simplify applica- 
tion program design and coding logic. The Utilities are 
table-driven; their actual operation is specified by user- 
coded tables generated via INTERCOMM macro instructions. A 
general description of each utility follows: 


THE EDIT UTILITY is used to prepare messages from on-line 
terminals for processing by the individual application pro- 
grams. It handles the overall processing of the incoming 
message, (e.g., stripping of T/P related control characters) 
and, in addition, edits and places the individual para- 
meters in the message into a predefined format. The module 
is driven by the EDIT Control Table (one table entry related 
to each independent message to be processed by the module) 
which defines the characteristics of each input message, the 
related editing function to be performed, and the format of 
the corresponding output (edited) message for either COBOL, 
PL/1, FORTRAN or BAL message processing subsystems. 


THE OUTPUT UTILITY is designed to provide simplified generation 
and revision of output formats to telecommunication devices 
without impact to the individual application subsystems. Each 
application program may use the module to generate its term- 
inal display formats or hard copy reports by passing to OUT- 
PUT the data fields that vary from message to message. The 
OUTPUT module will in turn: 


° Select the format to be used based upon table specifica- 
tions; 

° Locate the application variable data to go into the 
format; 

° Format the output message based on an device dependent 


constraints such as line-ending sequences, and line and 
buffer size. 

° Insert the necessary T/P control characters related to 
the transmission of the message; and 


s Output the actual message(s) to the Telecommunications 
module for transmission to the designated terminal. 


THE DISPLAY and CHANGE UTILITY are intended to allow a remote 
terminal operator to display an individual file record (for 
BDAM, ISAM or VSAM files) ina fixed character format on his 
terminal, and then in turn to modify selected fields within 
the file record that he had just displayed. The module, 
Similar to EDIT and OUTPUT, is totally table-driven. There 
is no program modification required for any fixed format file 
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records. The only item required by the user for the display 
of record data (binary, hexadecimal or character) is the 
Format Description Table entries defining the characteristics 
of the individual file records. 


Choice of which Utilities are in use at INTERCOMM execution 
time is a matter of using INCLUDE control cards for the 
individual modules in the INTERCOMM link-edit. The EDIT 
Utility operates as a system service routine and is CALLed 
whenever EDITing functions are required. CHANGE/DISPLAY and 
OUTPUT operate as message processing subsystems and hence are 
scheduled for execution by the INTERCOMM monitor. Terminal 
input transactions for CHANGE/DISPLAY are queued, scheduled, 
and processed automatically by the standard INTERCOMM facili- 
ties. Application subsystems (and INTERCOMM modules as well) 
create and queue messages to be processed by the OUTPUT Utility 
via standard INTERCOMM service routines. 


There is one set of operational tables in the production en- 
vironment. Hence, the INTERCOMM System Manager has the final 
responsibility for controlling the tables used at execution 
time. This person (or persons) must ensure the accuracy of 
all new table entries created by application personnel and 

may specify which particular table entries may be core or disk 
resident considering system throughput and response time 
requirements. 


Certain manufacturer's terminals have hardware operating 
features necessitating special coding conventions for the 
EDIT and/or OUTPUT Utility Tables. These terminals and the 
procedures for defining their use with the Utilities are 
described in a separate section. 


All tables for the Utilities are summarized in Appendix A, 
Appendices B, C, D contain table-oriented macro coding 


specifications. 


THE EDIT UTILITY 


GENERAL DESCRIPTION 


The EDIT Utility is provided with INTERCOMM to relieve the 
user's application program from terminal and format dependent 
considerations. All messages entering the computer from remote 
terminals have three standard characteristics which make all 
application programs unnecessarily complex. They are as 
follows: 


1. Teleprocessing control characters are embedded 
throughout the message. 

2% In many cases, the terminal operator need not enter 
all fields in a message. Application program logic 
is required to determine which fields were entered in 
each input message. 

3. If the operator enters fields in error, application 
program logic is required to handle these errors 
by analyzing them and then either rejecting the 
total message or accepting the message while omit- 
ting processing of the erroneous parameters. 


The EDIT Utility provides an interface under which the applica- 
tion programmer need not be greatly aware of these problems. 


The EDIT Control Module, in conjunction with standard INTERCOMM 
Supplied subroutines and optional uSer-supplied EDIT subroutines, 
provides field-by-field editing of all fields input by the 
remote terminal operator. The entire input message is edited 
and formatted as specified by the user in the EDIT Control 

Table. Errors relating to invalid fields supplied by the 
terminal operator are diagnosed by the Editing modules and, 

when appropriate, error messages are sent to the terminal 
operator. 


Every transaction entered from a remote location is identified 
by a 4-character transaction identifier (verb). Editing of an 
incoming message is performed when specified by the Verb Defini- 
tion in the INTERCOMM BTAM Front-End Verb Table or based upon 
low-value (X'9Z') in the Verb/Message Identifier (VMI) in the 
message header. The EDIT Utility is activated when: 


‘ Message processing is to be initiated by a subsystem 
coded ina high level language. The INTERCOMM language 
interface module CALLS the EDIT Utility. (A subsystem 
receives only successfully EDITed messages.) 


oa A BAL subsystem CALLs the EDIT utility directly. (The 


BAL subsystem logic defines recovery from unsuccessful 
EDITing.) 


10 


J 


‘. The INTERCOMM BTAM Front-End CALLS the EDIT Utiliity. 
(Messages not successfully EDIT'ed are not queued for 
message processing.) 


Messages created by one subsystem and queued for processing 
by another subsystem may be EDIT'ed if desired by setting the 
message header VMI to low-value (X'@@%') and creating message 
text in a valid format for EDIT. 


Figure 1 illustrates the options for input message formats, 
and EDITed results. 


INPUT FORMAT OPTIONS 


The EDIT Utility can accept input from a remote terminal in 
either of four formats called the Keyword Format, the Posi- 
tional Format, the Positional by line Format, and the Posi- 
tional Within Keyword Format. 


Each mode of input has advantages that the user should weigh 

in determining which format to use for each transaction input 

to INTERCOMM subsystems. Note that it is NOT mandatory for 
Subsystems (application programs) executing under INTERCOMM 

to use the EDIT Utility; this Utility can be completely by- 
passed for any given transaction type. Any mixture of input 
modes may be used for different transaction types. For example, 
assuming an installation that has 5 different transaction types, 
the possibilities are that: 2 transaction types are not edited 
at all; 1 transaction type is entered in Keyword Format; 2 
transaction types are entered in Positional Format. 


In this section, the conventions for input message formats 
are denoted by: 


Cj the field separator character defined in the installa- 
tion's system parameter list (SPA). 


A the new line, carriage return, or carriage return/line 
feed sequence of the terminal. 


O the End of Message sequence of the terminal (EOT, EOB, 
ETX, ENTER, etc.). 


In general © and A are interchangeable. 
Keyword Format 


When data is to be supplied in the Keyword format, the mes- 
sage is entered in the following manner: 


ll 


TERMINAL SUBSYSTEM 


Resa 


VERBt+character text header intersubsystem text 


ae 


NO 


YES 


header 
VMI=X' $@'| VERB+keyword or positional text 


message text 


ee ey i. eee 


EDIT 
UTILITY 


fixed or variable format 
fields 


SUBSYSTEM 


Figure A. EDIT Format Options 


LZ 


ae . 
terminal or intersubsystem 


J 


TRNS A (Verb or transaction identifier) 
CUS JOHN R. WILLIAMS, JR. A (customer name) 


ADR 727 E. 43rd St. A (customer address) 

C/S WEST HEMPSTEAD L.I. A (customer address) 

ACT 7432710 A (customer account number) 
DBT $27.42 A (debit amount) 

CRD S127 LZ (credit amount) 

END O 


The four character verb is the first field of each message. 
Each data element in the message is identified by a unique 
three character field identification. The field identifica- 
tion is immediately followed by the data for that field. 

(Any number of separating blanks can be inserted between 

the field ID and the actual data; these blanks are eliminated 
by the EDIT Utility.) The field ID (or keyword) must be 
unique within any one transaction type; it may be reused in 
other transaction types. For example, the letters CUS may 

be used in all transaction types that require a customer name 
to be entered. 


For data elements that can be entered more than once ina 
particular input message, the terminal operator simply enters 
the given keyword more than once in the message; each use of 
the keyword is followed by the appropriate data. Thus, in 
the example above, if it were possible to have three debit 
amounts, the data entered would be as follows: 


DBT $27.42 A (debit amount #1) 


DBT §$ 7.93 A (debit amount #2) 
DBT $ 8.47 A (debit amount #3) 


The terminal operator must be taught the proper keywords to 
use on input. Any field not applicable on the current entry 
can be omitted by not entering that Keyword (and data) in 
the message. In addition, the fields may be input in any 
order. 


An additional advantage of the keyword format is the capa- 
bility of using the CANCEL and CORRECT options. The CANCEL 
option is intended to give a remote terminal operator the 
ability to cancel a message that has already been entered 
if it is determined that something iS wrong with the fields 


entered. (This is particularly useful when using unbuffered 
devices where each character entered is transmitted imme- 
diately.) If an error is realized before the End of Message 


sequence (©) has been entered, the remote terminal operator 
can type the following: 


L3 


END A 
CANCEL A 


END © 


The EDIT Utility will then cancel the message when it is called 
upon to Edit this transaction. (The use of CANCEL is only ap- 
plicable if the transaction is to be Edited by the EDIT 
Utility.) 


The CORRECT option is used in similar circumstances when the 
remote terminal operator wishes to correct one or more fields 
previously entered, rather than cancel the entire message. 
Suppose that the following message had been typed: 


CUS JOHN R. WILLIAMS, JR. A 
ADR 727 E. 43 st. A 

C/S WEST HEMPSTEAD, L.I. A 
ACT 7432710 A 

DBT $27.42 A 

DBT $ 7.93 A 

DBT $ 8.47 A 

CRD $1.27 A 

END A 

CORRECT A 

ACT 7432794 A 

DBT (2, 9.74) A 

END QO 


trys A 
! 
| 


The EDIT Utility will reformat this message as if it had been 
entered in the following form: 


TRNS A 

CUS JOHN R. WILLIAMS A 
ADR 727 E. 43 sSTL. A 

C/S WEST HEMPSTEAD L.I. A 


ACT 7432794 A (corrected field) 
DBT $27.42 A 
DBT $ 9.74 A (corrected field) 


DBT $ 8.47 A 
CRD $ 1.27 A 


END © 
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The first field entered after END and CORRECT was a correction to the 
customer account number; only the corrected number is recognized by Edit and 
given to the application program. The second field entered is a correction 
to the debit amount which in our example is a repetitive field. Thus it is 
necessary to specify which debit amount is to be corrected. This is 
indicated by using the following form: 


kkk (n, data) 
where: 


kkk is the keyword to CORRECT; 
n, is the occurence number of the keyword; 
data is the corrected data to replace the original data entered. 


The data entered in the example above corrects the second data field 
identified by the keyword DBT. 


Positional Format 


When entering data in the positional format, only data fields are 
entered; no field identifications are used by the remote terminal operator. 
The data fields are seperated by the system-wide field separator character 
(()). The example given in the section describing the keyword format would 
be entered in the following manner using positional format: 


TRNS[] JOHN R. WILLIAMS (| 727 E. 43rd St. [1 WEST HEMPSTEAD L.I. A 


743279100 $27.42 O $1.270 


As the example illustrates, the transaction identification (verb) is 
also required in this format. Every possible field for the particular 
message type must either be supplied by the terminal operator or indicated by 


the insertion of an extra separator character to indicate the absence of the 
field. 


Blanks may be present within a data field (as in the name entered 
above); however, the first character of a data field may not be blank. 


Positional by Line Format 


The operator may also be instructed to enter positional data fields in 
a predefined line sequence, in which case separator characters are not 
required for omitted fields trailing at the end of each line. For example: 


TRNS A 
JOHN R. WILLIAMS ( 727 E. 43rd ST. 1 WEST HEMPSTEAD, L.1I. A 


7432710 A (account number) 
$27.42 A (Debit field(s) line) 
$ 1.27 0 (Credit field(s) line) 
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The number of debit and credit fields is limited by the 
line width of the terminal. 


Positional Within Keyword Input from a Remote Terminal 


Positional Within Keyword Terminal Input combines the ad- 
vantages of Keyword input and Positional input. The field 
identifications (Keywords) are followed by corresponding 
positional data items. Within any Positional Within Key- 
word Line, only data is entered; no individual field iden- 
tifiers (Keywords) are used by the remote terminal operator. 
Note, however, that each keyword defines a new line format 
and all fields defined on a particular Positional Within 
Keyword Line must be given in the respective sequence within 
that line. 


When data is to be entered by the remote terminal operator 
in Positional Within Keyword format, the message is entered 
in the following manner: 


TRNS A 
CUS JOHN R. WILLIAMS([ 7432710 A (name, acct #) 


ADR 727 E. 43rd ST.—Q] WEST HEMPSTEAD, L.I.A (address) 
INF $27.420$1.270 (debit, credit) 


The four character Verb, as always, is the first data field. 
In Positional Within Keyword Format, the Keyword Identifier 
does not have specific fields associated with it. Instead, 
it is associated with a line of positional data. The 
keywords and the corresponding lines of positional data 

may be entered in any order. The data within any line, . 
however, is positional and therefore must be entered in the 
predefined order for that line. 


The data fields within the Positional Within Keyword Line 

are separated by the system Separator character (()). Every 
possible field within a particular Positional Within Keyword 
Line must either be supplied by the terminal operator or 
marked by insertion of an extra separator character to in- 
dicate the absence of the field. Any omitted fields at the 
end of a line do not need separator characters to define their 
absence. The end of line sequence (A) defines the absence of 
trailing fields that have been omitted. If, in the above ex- 
ample, in the INF line, it was desired to only enter a credit 
amount, that line could be entered as follows: 
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INF£1$27.42 A 


Video Display Terminals With Screen Formatting 


Certain Video Display Terminals have the facility to display 
"format" screens for the operator's convenience. For example: 


TRNS 
Sate e: lanes Gator Gt ices Re es ee ve veieey eeilere erie CUSTOMER NAME 
Sans fas is ho HRP Gabriel eh Fan Gish stoic des Bh dae, tate ss tat alts Sens oe ath Soh a ee ADDRESS 
Bloc Tes sel ch Tati ca Declare ee tai le eet nek eet ACCOUNT NUMBER 
BG Mer ier ser ey srr wit) Sia aie, tees cer Tes, Be age ke ee ta ete eet eee ee eco ys Be. Wes oie hes nak Ae). case DEBITS 
Site. Toh et tas eins ee betes eee Bie. Zatter otse Veron ewes! Shady orden ue wee Sno 0p weeds eran CREDITS 


where colons (or some other terminal dependent character) 
delimit those screen positions where an operator may enter 
data. Only the data within colons is transmitted as an input 
message. 


In some instances the terminal itself will generate a tab 
character (or other terminal dependent character) at the 

end of each "formatted field" entered by the operator. In 
this instance, the tab character may be defined as the separ- 
ator character (O01) for the installation and the incoming mes- 
sage would correspond to standard Positional input to the 
EDIT Utility: 


TRNSCL] NAME 1 ADDRESS (J DEBIT(S)O) CREDIT(S)© 


However, special consideration must be given to the hardware 
operating considerations of each terminal type to ensure that 
this standard format is maintained. 

See the section "Terminal Dependent Considerations" for these 
devices which the EDIT Utility treats ina special fashion due 
to their hardware characteristics. 

EDIT PROCESSING 


Edit Components 


The Edit Utility consists of a major EDIT Control routine, 
specific EDIT Subroutines (INTERCOMM and uSer-supplied), and 
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an Edit Control Table (ECT) generated by INTERCOMM macros, 
and a Pad Character Table. Figure 2 depicts the functional 
components of the EDIT Utility. 


EDIT CONTROL INTERCOMM 
TABLE EDIT 
(ECT) SUBROUTINES 


EDIT 
CONTROL 


ROUTINE 


PAD OPTIONAL 
CHARACTER USER-CODED 
TABLE EDIT 
SUBROUTINES 


Figure 2. Functional Components of EDIT 


The EDIT Control Routine provides total input message analysis, 
controls the calling of the individual EDIT subroutines based 
on the actual message and specifications in the EDIT Control 
Table, and produces the EDITed message. 


The individual EDIT Subroutines called by the EDIT routine 
provide a field-by-field edit of the data items supplied by the 
remote terminal operator. The interface between the main EDIT 
Routine and any EDIT Subroutine is a standard CALL statement. 
The user's individual EDIT Subroutines, coded for special 
functions, can be written in either Basic Assembler Language 
(BAL) or any of the higher level languages, (COBOL, FORTRAN, 
PL/1). 


The EDIT Control Table contains one entry for each incoming 
verb to be edited specifying general characteristics of the 
message, and detail requirements for field editing. Table 

entries may be core or disk resident. 


The Pad Character Table defines pad (fill) characters to be 
used when edited fields are less than the length requirement 
of the EDIT Control Table. 


Edit Control Routine Logic 


When CALLed, the EDIT Control Routine (hereafter referred to 

as EDIT) is passed the address of the message input from the 

terminal. The verb in the message text is utilized to locate 
the specific EDIT Control Table (ECT) entry. EDIT logic then 
proceeds as illustrated in figure 3: 


Ls EDIT acquires a new area Of core for the edited 
result. 
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2. EDIT copies the input message header to the edited 


Cc result. 

| 3. The Verb/Message Identifier (VMI) in the message 
header is set to a one-byte value according to the 
ECT specification, effectively replacing the VERB. 

4. An individual data field is isolated, and EDIT finds 
the entry in the EDIT Control Table describing the 
field to be edited. From the table, EDIT determines 
which EDIT Subroutine is to do the edit checking 
and/or conversion of the data supplied; the EDIT 
Subroutine is then called. Upon return from the 
subroutine, the length of the edited data is com- 
pared to the length specified in the ECT for this 
field. If they are equal, no action is required. 

If the edited data length is larger, it is truncated 
on either the left or right as specified by the ECT 
(if truncation is allowed). If truncation is not 
allowed, the data item is rejected. If the edited 
data length is less than the maximum length for this 
field and the field is always to be given a fixed 
length (as specified by the ECT), the field is padded 
with the appropriate pad character from the Pad 
Character Table based on the EDIT Subroutine used. 
If the field is numeric, the field is padded on the 
left; otherwise it is padded on the right. If the 
field is not fixed length, the data is not padded 

at all. 

5. The next field in the input message is then isolated 
and is processed as described above. Processing 
continues until all fields of the input message have 
been EDITed. 


The EDIT Control Routine strips the following field 
definition characters during the course of editing: 


A The system separator character (4), as de- 
fined in the System Parameter List (SPA); 

New line characters (A); 

Z Carriage Return or combined Carriage Return/ 
Line Feed (A); 

. End of Text, End of Message, End of Block, 
or End of Transmission (OQ); 


All other device control characters not translated or 
otherwise suppressed by the front end translation table 
for a particular device will be treated as text within 
a field. 

6. When all input fields have been processed, EDIT 
adjusts the length field in the message header to 
reflect the actual length of the edited result, frees 
the remainder of storage not used and frees the 
original incoming message. 


Cc EDIT considers its processing successful if no required fields 


(as defined by the ECT) were omitted or given in error. The 
EDITed result is returned to the CALLing program as an address 
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in its original parameter list. Non-required fields not 
edited successfully are indicated by high-values (X'FF') in 
the appropriate field location in the EDITed result. ) 


EDIT returns error messages to the originating terminal (via 
the Output Utility) for each required field omitted or in 
error. The CALLing program is notified of EDIT's rejection of 
the incoming message by a zero address in its original para- 
Meter list. The storage occupied by the EDITed result is 
freed. Similarly, if the transaction type (verb) entered is 
not defined in the EDIT Control Table, a zero returned as the 
address of the edited message indicates an unsuccessful EDIT. 


EDIT 
SUBROUTINES 


(6) (3)}data 1{ data _n| 
» 
(2) EDITED Result Area J 


Figure 3. EDIT Control Routine Logic 
EDIT Subroutines 


The EDIT Subroutines supplied by INTERCOMM provide for basic 
editing capabilities necessary for any installation. They do 
numeric checking, convert data to packed decimal, convert data 
to binary, etc. In addition, there are unique routines for 
use in INTERCOMM applications. For example, one EDIT Sub- 
routine validates an input field to check for valid terminal 
identification for the Output Utility. 


The EDIT Subroutines are identified by number (nnn), where the 
subroutine entry point is coded as EDITnnn. EDIT Subroutines 
000 thru 020 are reserved for INTERCOMM routines, 021 thru 255 
may be utilized as identifiers of user specified EDIT Sub- 
routines. 


Each field in the incoming message is edited by one subroutine 
indicated in the EDIT Control Table entry by number. INTERCOMM- 
supplied subroutines are described in figure 4. The routine 
numbers in figure 4 are values to be given on the PARM macro ‘ 
as the EDIT Subroutine number (see Macros Manual). Techniques J 
for coding user-supplied EDIT subroutines are described later 

in this section. 
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c | Routine 


Number Description 


Determines the length of a character field and 
places actual data into the output area for 
the field. 


Determines the Length of a character field, 
checks for valid numeric data, packs the data, 
and puts the packed data into the output field. 
Maximum length edited data can be is 15 bytes. 


Acts like Routine 1, but converts data fields 
to binary. Maximum length edited data can be 
is 4 bytes. 


Acts like Routine 1, for dollar amount fields,. 
stripping dollar sign and decimal point and 
converting to packed decimal. 


_ 

os 

* | Reserved for future use. 
‘av 

i 

- 


Converts YES or NO fields. YES is converted to 
a Character 1; NO is converted to Character O. 


Validates that a terminal identification given 
as a character data field is contained in the 


OUTPUT Utility Station Table. 


Acts like Routine @ for numeric cnaraecter data 
which is to remain as unpacked data. 


Acts like Routine 1 for dollar amount fields, 
Stripping dollar sign and decimal point and con- 


verting to binary data. (Maximum length edited 
data can be is 4 bytes.) 


3 
7 
20 


9- Reserved for future use. 


( Figure 4. INTERCOMM Edit Subroutines 
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DATA FORMATS AFTER EDITING 


Once all fields of the input message have been edited success- 
fully, a message formatted by the EDIT Control Routine is ready 
for processing by an INTERCOMM subsystem. The definition of 
required format results from EDIT processing is contained in 
the EDIT Control Table entry for each transaction type (verb). 
Thus, each transaction type can result in only one format. 
Different transaction types may result in different formats 
after EDITing. 


Fixed Format 


When called upon to produce data ina fixed format, the result 
of EDITing consists of data fields in a predefined sequence 
with each EDITed field a predefined fixed length. The user 
specifies the sequence of fields in the EDIT Control Table. 
Graphically, the message appears as: 


Standard Field 1 Field 


42 byte Header data data 


The data given in the example earlier in this Section might be 
presented in the following format to the application program: 


INTERCOMM MESSAGE HEADER | JOHN R. WILLIAMS JR. 
727 E. 43rd ST. | WEST HEMPSTEAD L.I. 00 74 32 71 | OS 


O24 P41 29S 004.99 | 8S f00-1-84")- 7s) 00 12. 7s 


All fields have been formatted and edited as specified in the 
EDIT Control Table (Notice numeric fields were edited to 

packed decimal with S representing the Sign character). It is 
important to note that regardless of the form of input supplied 
by the remote terminal operator, the field lengths and start- 
ing positions of each field in the message will be fixed for 
each EDITed message passed to the application program for 
processing. 


If a data item was not supplied on input from the remote 
terminal, the pad character defined for the EDIT Subroutine 
which edited the field is used as a fill character for the 
entire field. This can be used as a basis for checking if a 
given field was omitted on input. If the data item was sup- 
plied erroneously on input, the field will be filled in with 


22 


J 


high values (X'FF' in each byte of the field). This is only 

Meaningful, of course, if the data item was specified as not 

required since if a required field is given in error the mes- 
sage is rejected by the EDIT Routine. 


Variable Format 


When using the variable format of presenting data to an 
application program, EDIT selects each field from the in- 
coming message and places it in the message being produced 
with a 2 or 3-byte prefix based upon ECT specifications as 
follows: 


L 


Ii E 
C] N data 


where 


Ic is the Item Code (defined by the ECT) to identify the 
field. 


‘ LEN is the length of the data field (plus one if oc# 
exists) 


; OC# is the occurence number for repetitive fields. 


The data elements in the message produced are in the order 
entered by the operator. Application program logic is re- 
quired to scan the message to locate particular data fields. 
In the example given in Section B, the data would be pre- 
sented in the following form: 


INTERCOMM MESSAGE HEADER | 01 | 14 | JOHN R. WILLIAMS, JR. 
02 | OF | 727 E. 43rd st. | 03] 13 | WEST HEMPSTEAD L.I. ga 


05] 00] 74 {32{ 71 {]0S | 05; 044, O1] 02); 74] 2S] 05] 04 


It should be noted that the same item code (05) is used for 
all of the debit amount fields given, the first time assign- 
ing an occurrence number of Ol, the second time an occurrence 
number of 02, and the third time an occurrence of 03. Notice 
that the length field includes the length of the occurrence 
number byte for repetitive fields. Note also that in the 
variable format, the user has the option of always passing 
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the data with a fixed length, padding where necessary (as was 
Gone for the second and third debit amount fields above) or 
of passing only the data supplied with no unnecessary padding 
(as was done for the credit amount field). 


Variable format result of EDITing allows an application program 
to access a string of Status Bytes showing which fields 
appeared in the incoming message. Status Bytes and their for- 
Mat are discussed later in this Section under the topic "Edit 
Error Analysis." 


EDIT TABLES 
The EDIT Control Table 


The EDIT module is driven by the EDIT Control Table (ECT). 
This table contains all information about each message neces- 
Sary to perform editing. 


The ECT resides in core, in a separate CSECT labelled 

VERBTBL. (The address of the EDIT Control Table appears 

in the System Parameter List.) The ECT contains actual EDITing 
specifications or optionally may contain pointers to disk- 
resident entries. In general, frequently processed transac- 
tion types (verbs) utilize core-resident entries for fast 
retrieval of EDIT specifications; transactions with low 

volume utilize disk-resident entries. 


The EDIT Control Table is a variable length table, and is 
created and maintained by the user. The following INTERCOMM 
macros are used to create the ECT: 


: VERBGEN is a macro which must precede the table entries 
if any VERB macros contain the RBN= parameter to signify 
actual table entry is disk resident. (If no ECT entries 
are to be on disk, VERBGEN is omitted.) 


, VERB is the macro defining general editing specifications 
(the transaction id or actual 4-character verb, input 
format, edit result format, etc.) 


; PARM is the macro defining specific edit requirements 


for each data field (edit subroutine number, required 
field, truncation, maximum length, etc.) 


PMIELIN is the macro delimiting positional data fields 
by line. 


é PMISTOP is the macro signifying end of the ECT. 
Coding specifications for these macros are described in detail 


in Appendix B. Figure 5 illustrates the general structure 
of the EDIT Control Table. 
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VERBTBL CSECT 
VERBGEN 
VRB1 VERB FIRST VERB 
PARM FIRST PARAMETER FOR VRB1 


PARM (N) th PARAMETER FOR VRBIL 
VERB SECOND VERB 

PARM FIRST PARAMETER FOR VRB2 
PARM SECOND PARAMETER 

PMIELIN END OF POSITIONAL LINE 


PARM (N)th PARAMETER FOR VRB2 
VERB RBN=1 VERB POINTER FOR DISK 
RESIDENT ENTRY 


VERB (N) th VERB 


PARM (N) th PARAMETER FOR 
(N) th VERB 

PMISTOP 

END 


Figure 5. EDIT Control Table Structure 


Each individual table entry consists of one VERB macro and one 
or more PARM macros. Figure 6 illustrates allowable combina- 
tions of formats and VERB macro operand coding required. 


INPUT EDITED - VERB MACRO OPERANDS 
FORMAT | FORMAT | [_LINE=_ 


a 
=e 


Fixed 


ee |e 
eee 


i a 


Figure 6. VERB Macro and Message Formats 


Positional 
By-Line 


Positional 
Within 
Keyword 
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There is a distinct relationship between the order of the 
PARM macros and the VERB specifications for input message 
formats and resultant edited message formats. 


The relationship between the PARM macros and message formats 
is as follows: 


For Keyword Input Format: No correlation exists between 
the order of the description of the fields in the EDIT 
Control Table via PARM macros and the order in which the 
actual data is entered. 


For Positional Input Format: The order in which the fields 
are entered by the remote terminal operator must correspond 
exactly to the order in which the fields are described by 
PARM macros in the EDIT Control Table. 


For Fixed Format EDIT Result: The order in which fields 
are sequenced in the edited result corresponds to the 
order of the PARM macros. If a message field appears on 
the input message more than the maximum number of times, 
specified by the PARM macro fields, the extra fields are 
rejected. The application programmer using fixed format 
editing must know the format of the EDIT Control Table; 
the position of a data field in the edited message is 
completely controlled by the coding of the EDIT Control 
Table when using fixed format. 


For Variable Format EDIT Result: There is no correlation 
between the order of the PARM macros in the Edit Con- -- 
trol Table and the data presented to the application when 
using variable format. The data fields appear in the 
order entered in the input message. 


Thus, the ordering of the PARM macros in the EDIT Control 
Table has the following implications: 


di 


If Keyword Format input is being used, the order 
of the PARM macros in the table is used only to 
define the order in which the data is to be ar- 
ranged for the application program when fixed 
format results are specified. 

If Positional Format input is being used, the 
order of the PARM macros in the table defines 


both the order in which the data fields are entered 


on the input device and also the order in which 
the data is to be arranged for the application 
program. 
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3% For positional by Line Input Format, the allocation 
of fields to a line is defined by the PMIELIN macro 
(coded after each set of PARM macros which define 
a line) and hence the order of the PARM macros 
defines the order in which the operator may enter 
data. 

4, For positional Within Keyword Format: No cor- 
relation exists between the order of the description 
of the parameters in the Edit Control Table and 
the order in which the keyword lines are entered. 
However, for the positional data within any given 
line, the order in which the fields are entered by 
the remote terminal operator must correspond exactly 
to the order in which the PARM macros are sequenced 
for each keyword. 


Creating and Maintaining the ECT 


All INTERCOMM messages processed by the EDIT Utility share the ie= 
Same EDIT Control Table (both core and disk resident). Hence, 
Maintenance of this table in the production (live) version 

of INTERCOMM should be the responsibility of the INTERCOMM 

System Manager. 


There is one entry in the ECT for each verb to be edited. 
Core resident table entries are added to an existing ECT. 
Disk resident table entries are also contained in the core 
resident ECT to allow calculation of the actual disk resident 
entry length. The entire disk resident entry should be coded 
as though it were to be core resident; and is actually as- 
sembled as part of the resident table. After assembly, only 
the generation of the VERB macro remains in the resident 
table to specify the location of the disk table entry. The 
VERB and PARM macros for a disk resident table entry are 
assembled a second time to create a separate load module 


to be retrieved from disk when required. The Section 
"Disk Resident Tables for the Utilities" details procedures 
for loading disk table entries. For example, an ECT with 


core and disk resident entries might be: 
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VERBTBL CSECT 
* DISK RESIDENT ENTRIES INCLUDED 
VERBGEN 
* TRNB ECT ENTRY IN CORE 
TRNB VERB TRNB,3,256,2,KEY=NO 
PARM NUM,1,1,8,169@6111 CUST.NUMBER 
PARM AMT,2,1,8,1996@111 DEBIT AMOUNT 
* TRNS ECT ENTRY ON DISK 
TRNS VERB TRNS,1,256,2,RBN=1 
PARM CST,1,6,38,16696111 CUST.NAME 
PARM ADR,2,8,38,1669@111 CUST.ADDR. 
* TRNA ECT ENTRY ON DISK 
TRNA VERB TRNA,2,256,3,KEY=NO, LINE=YES ,FIX=NO, 
RBN=2 
PARM CST,1,8,38,1668G111 CUST.NAME 
PMIELIN END OF I/P LINE 
PARM ONM,2,1,8,1669@111 OLD CUST.NUMBER 
PARM NNM,3,1,8,1669@111 NEW CUST.NUMBER 
* END OF TABLE 
PMISTOP 
END 


The resident table CSECT name must be VERBTBL. The disk resi- 
dent entries are each contained ina block (RBN) of the BDAM 
dataset with ddname VRBIOSG. ) 


The ECT is searched sequentially; frequently accessed entries 
should appear in the beginning of the table. Since the disk 
resident table entries are assembled separately (without 
CSECT, PMISTOP and END macros), they may be maintained as 
members of symbolic libraries and COPYed into the resident 
CSECT for assembly; for example 


VERBTBL CSECT 
VERBGEN 

* CORE RESIDENT ENTRIES FOLLOW 

TRNB VERB 
PARM 
PARM 

TRNC VERB 
PARM 


* COPY EACH INDIVIDUAL DISK RESIDENT ENTRY 
COPY TRNSTBL 
COPY TRNATBL J 
PMISTOP 
END 
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The Pad Character Table 


The Pad Character Table supplies the EDIT Control Routine with 
the character to be used for padding with each EDIT Subroutine. 


The Pad Character Table is a resident CSECT named PADDTBLE. 

Each entry in the table is two bytes long. The first byte 
contains the number of the EDIT Subroutine with which the pad 
character is associated. The second byte contains the actual 
pad character. These entries are coded using the PADD macro or 
hexadecimal constants. The table must end with a PMISTOP macro. 


If no pad character is supplied for a particular EDIT Subroutine 
a default of blank (X'40'), is assumed. A pad character of 
Xx'oc', X'OD', or X'OF' will pad a packed field with binary 
zeros, but when no data is supplied fer the field EDIT will 
insert a sign in the rightmost byte (i.e., fill the field with 

a packed zero). 


The following entries appear in the pad table as supplied in 
the INTERCOMM release: 


TITLE '*** PMI-INTERCOMM *** PADD TABLE' 
PADDTBLE CSECT 

PADD 0O,BLANK ROUTINE - ALPHANUMERIC 

PADD 1,0F ROUTINE PACKED 

PADD 2,BZER ROUTINE BINARY 

PADD 3,0F ROUTINE PACKED DOLLAR 


PADD 5,BZER ROUTINE NO 

PADD 6,BZER ROUTINE TPU 

PADD 7,F0 ROUTINE NUMERIC CHAR 
PADD 8,BZER ROUTINE BINARY DOLLAR 
PMISTOP 

END 


In the following sample Pad Character Table, a pad character of 
blank has been assigned to EDIT Subroutine 21 and a pad char- 
acter of asterisk has been assigned to EDIT Subroutine 22. 


PADDTBLE CSECT 


: standard INTERCOMM 
: entries 


PADD 21,BLANK 
PADD 22356 


PMISTOP 
END 
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SAMPLE TABLE ENTRIES 


The examples in this section are included to assist the user 
in understanding the table entries specifying different options 
for input message formats and resulting EDIT data formats. 


The examples illustrate: 


Keyword Input, Fixed Format Result (Figure 7) 


Keyword Input, Variable Format Result (Figure 8) 


Positional Input, Variable Format Result 


: Positional by Line Input, 


: Positional Within Keyword Input, Fixed Result 


3 Verb only Result (Figure 12) 


Each example illustrates input from terminal, 
EDITed result. 


30 


Fixed Format Result 


(Figure 9) 


ECT entry, 


(Figure 10) 


(Figure 11) 


) 


eT 


Message Input at Terminal: 


PRCOA 

PO# 174321 A 
PRD 7450RA 
OTY 12A 

UNT DOZA 
PRD 863PLA 
OTY 1094 
AGN X71A 
END O 


Message received by EDIT: 


VMI ; 
header 06! PRCOAPO# 174321A PRD 7450RAOTY 12AuNT DozA 


3 PRD S63PLA QTY 166A AGN x71A ENDO} 


EDIT Control Table entry: 


PRCO VERB PRCO,@A,256,11,FIX=YES 
PARM PO#,§1,81,6815,18889111 
PARM PRD,@2,08,065,18@81111,REPT=3 
PARM QTY,§3,62,664,16881111,REPT=3 
PARM UNT,$4,00,603,090091111,REPT=3 
PARM AGN ,05,0902,063,10£06111 


EDITed result: 


VMI 
header DR | P20LPL0 062000 000000600174321F| F7F4F5D8D9 


F8F6F3D7D3 | 4040494049 | BOPPOSHC | POPP HH64 | BYOB ORE 
7 494949 | 494940 


I 


Figure 7. Keyword Input - Fixed Format Result. 


Sd: 
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PRCOA 
PO# 
PRD 
QTY 
UNT 


PRD 
QTY 
AGN 
END 


Message rece 


header DD 


PRD 863PLA QTY 198/\AGN X71 AENDO 


EDIT Control 


EDITed Resul 


1] 64) g174321F | g2| 66] O11) F7F4F5D8D9 


93492! gl 
G3 | G2 | G2 


Figure 8. Ke 


Message Input at terminal: 


174321A 
7T450R A 
112A 
poz A 
863PLA 
1fGA 
X71A 

O 


lived by EDIT: 


PRCOAPO# 1743214 PRD 745Q9RA QTY 12AuNT DozA 


Table Entry: 


PRCO,#A,265,5 
PO#,#1,81,815,16906611 
PRD, $2,00,005,10961111 


QTY, £3,62,604,16GH1611 
UNT, $4,928,603, 066801111 
AGN, $5 ,86,893,18989111 


ts 


gC} G4; G4| G1 | C4D6EOS | 92] GO| G2} F8FEF3D7D3 


64 | 65] 963 | E7F7F1 


y Word Input - Variable Format Result. 
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Message Input From Terminal: 


INVCO1@KR301901500500 


Message Received by EDIT: 


header 68] INVCO19@KR3Q1901500500 


EDIT Control Table Entry: 


INVC,9B,256,7,KEY=NO 
PARM ITN ,91,668,865,186866111 

ADD,92,62,084,86081911,REPT=3 
DEL, $3,892,084 ,80061811,REPT=3 


EDIT Result: 
header OB JOSSOSHA 
TITEL 3s Qi] POPIGG32 


Figure 9. Positional Input - Variable Format Result. 


Message Input from Terminal: 


INVCO1SKRBA 


19 
50 


o15sA 


Message Received by EDIT: 


[header g9| INVCO 16KR3A19015A50| 


EDIT Control Table Entry: 


INVC 


EDIT Result 


header @B 


VERB 
PARM 
PMIELIN 
PARM 
PMIELIN 
PARM 


INVC,@B,256,7,FIX=YES,KEY=NO,LINE=YES 
ITN, $1,698 ,905,1 6696111 


ADD ,$2,92,094,86061111,REPT=3 


DEL,£$3,602,004;$8081111,REPT=3 


FIF@D2D9F3 | PAUSVOOBA |] POBOOOOF | BABGOBOD 


|| SLOPPPB5 | OOPPPHOO | BABODADS | 


Figure 10. 


Positional by Line Input - Fixed Format Result. 
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Message Input from Terminal: 


TRNA A 
CUS PETER JONESO 10 ALLEN STU NY,NYA 
INF 176-42400$73.950 


Message Received by EDIT: 


| header 6@| TRNAACUS PETER JONESO10 ALLEN STO NY, ,NYA#® 
3 INF 176-424005$73.95 O | 


EDIT Control Table Entry: 


VERB TRNA,C1,256,8,KEY=YES,LINE=YES ,FIX=YES 

PARM CUS ,$£,0,0, 00060060 (CUS is a keyword) 
PARM NAM,61,6,25,$006G11B 

PARM STR,62,6,20,0000011f 

PARM C/S,$3,6,25,6D0608119 

PMIELIN 

PARM INF ,62,0,2, 08000 60D (INF is a keyword) 
‘PARM ACT,£4,23,7,0660611@ 

PARM DEB,@5,24,7,60066119 

PARM CDT,$6,25,7,06068112 


‘EDIT Result: 

| header ClIC'PETER JONESH BERBER REE MERRE'[C'1O ALLEN STHEBEMEE REY 
L_C'NY ,NYMB MBB BBB E EYEE Yee ye'| FIF7POFFFAF2F4 | SO9DSDOB SDS OGD | 

| P2GSBHGB0H7395s | 


Figure ll. Positional Within Keyword Input - Fixed Result. 
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An input transaction can be defined in the Edit Control 


Table with the parm parameter of the VERB macro equal to @. 


In this case, the edited message will consist of Header 
only. The 4-character input verb is indicated by the VMI 
value in the header. (No data may be entered at the 
terminal for this type of transaction.) 


EDIT Control Table Entry: 


| VERB CUST,1,256,09,FIX=YES 


EDIT Result: 


| header G1 | 


VMI 


Figure 12. VERB only RESULT. 
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( EDIT ERROR ANALYSIS 


Edit 


analyzes the results of editing by each individual 


subroutine and takes the following actions: 


REQUIRED Fields 


For errors and omissions of fields defined as REQUIRED in the 
PARM edit flags, error messages are sent back to _ the 
originator indicating the parm-name of the erring or missing 
field; all remaining fields are checked; non-Assembler 
subsystems will not receive any message to process. 


NOT REQUIRED Fields-Errors 


For errors in fields defined as NOT REQUIRED: 


1. Error messages are not sent to the originating terminal 
(unless Edit is reassembled with the global &EDDERS SETBd 
to 1 in SETGLOBE. Refer to the Operating Reference 
Manual, Section 8, for details.) 


2. For variable format Edit result, a string of status bytes 
included in the message text indicates field(s) in 
error. The field will not appear in the output message. 
If the field is a repeatable field, the "number of 
occurrences" in status byte B for the field does not 
include a count for the erred field. 


3. For fixed format Edit result, the corresponding output 
field will contain hexadecimals X'FF' (high value). 


NOT REQUIRED Fields-omissions 


Omissions of fields defined as NOT REQUIRED: 


1. For variable format Edit result, the status bytes for the 
omitted item code will indicate parameter not supplied. 


2. For fixed format Edit result, the field corresponding to 
the omitted item will contain the specified pad 
characters. If there is no pad character defined, it 
will contain blanks (X'40'). 
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Status Bytes (Variable Results only) 


In addition to returning the edited message to the CALLing 
program, Edit returns (as part of the edited message) status indicators 
for each field which was or could have been supplied for the message 
when using the variable format result of editing (two bytes per PARM 
macro). Edit puts the address of the string of status bytes in the 
third word of the original parameter list passed to Edit. The status 
bytes physically appear in the edited message text, identified by an 
Item Code of X'FF'. 


There are 2n+l status bytes where n is the number of different 
parameters which can be given for the message. The first byte 
represents a status indicator byte for the entire message (currently 
not in use). The next 2n bytes represent two bytes for each PARM macro. 


The status byte string is formatted as: 


Status | status status | status 


where: 
FF is the item code indicating status byte string 


mn indicates the length of the status bytes string if there are 
less than 127 parameters. Otherwise, this length is not used 


r is the reserved byte 


status byte A indicates: 
Bit 0 - Parameter supplied 


Bit 1 — Reserved 

Bit 2 — Reserved 

Bit 3 - Unused 

Bit 4 - Parameter given but in error 
Bit 5 - Unused 

Bit 6 - Unused 

Bit 7 - Reserved 


Status byte B represents the number of times the parameter was 
given in the message (always one for non-repetitive parameters; 
otherwise it can be any number). 
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Standard Error Messages 


Error messages reflecting problems encountered during editing of 
required fields are generated by the Edit Utility and queued for 
processing by the Output Utility. The messages are formatted according 
to Output Format Table entries. Each field found in error will cause 
an error message to be returned to the originating terminal. 


Each error message explicitly defines the reason for rejecting 
the input data, for example: 


NON-NUMERIC CHARACTER GIVEN ON xxx PARAMETER FOR xxxx VERB. 
ALL CHARACTERS SHOULD BE NUMERIC. 
MESSAGE NO. FROM TPU Ps 


OF s 


REQUIRED PARAMETER xxx WAS OMITTED (OR GIVEN IN ERROR) ON 
THE xxxx VERB. 
MESSAGE NO. FROM TPU ‘ 


For a precise listing of Edit Utility error messages, see the 


Intercommn Messages and Codes. 


CODING EDIT SUBROUTINES 


Each installation can write up to 235 user-edit subroutines, as 
needed, to perform application-oriented editing of fields coming into 
the system from remote terminals. These Edit subroutines are CALLed in 
a standard manner with the parameter list described below. The Edit 
subroutine can be written in Assembler, COBOL, or PL/1. (A sample edit 
subroutine coded in COBOL is illustrated below.) Since the subroutine 
is passed only actual field data, the problem of teleprocessing control 
characters need not be considered. 


The edit subroutines must have entry points named EDITxxx, where 
Xxx may be any number from 021 to 255. It is inportant to note that 
edit subroutines may be generalized. For example, EDITO21 can be used 
to edit any number of transactions types by coding 21 as the subroutine 
number in the appropriate PARM macro of the Edit Control Table (ECT). 


Note that the SPA CSECT must be reassembled to reflect the number 
of Edit subroutines in use (SPALIST macro, EDITRIN parameter). See 


Section 8 of the Operating Reference Manual for details. 


The edit subroutine logic may be used to construct an error 
message to the input terminal and queve it for the Output Utility. 
However, in order to build an output message, the edit subroutine must 
have access to the original input message header. Register 9 on input 


to the edit subroutine points to a location which contains the address 


of the input message being processed, and consequently may be used to 
locate the input message header. 
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The parameter list passed to an edit subroutine is as follows: 
1. Address of the unedited data field 
2. Address of the System Parameter list (SPA) 


3. Address of a one-word field containing the length of the 
unedited data 


4. Address of the field in which the edited data is to be placed 
(field is maximum of 255 characters in length) 


5. Address of a one-word field to place the length of the edited 
data 


6. Address of the status bytes for this parameter 
7. Address of the fullword return code field 


The return code field is used to indicate whether or not a field 
has passed its edit. If the field edit is not successful, the edit 
subroutine should place a non-zero value (binary) in return code field, 
and turn on bit 4 of the first status byte. A zero return code 
indicates successful edit. 


The following restrictions apply to edit subroutines coded in 
COBOL or PL/1: 


1. The subroutine may not give up control (no CALLs to COBREENT 
or PMIPL1). 


2. A COBOL-coded subroutine is not a_ subsystem; hence no 
"dynamic work space" is available. 


3. The subroutine must reside in Intercomm's transient 
subroutine overlay region. 
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The following is a sample edit subroutine coded in COBOL: 


ID DIVISION. 

PROGRAM-ID. EDIT 204. 

AUTHOR. PROGRAMMING METHODS. 

DATE-COMPILED. 

REMARKS. INTERCOMM EDIT OF ONE-BYTE FIELD FOR A, C OR D. 


ENVIRONMENT DIVISION. 
DATA DIVISION. 
WORK ING-STORAGE SECTION. 


LINKAGE SECTION. 


01 IN-FIELD PIC X. 

Ol SPA PIC X. 

01 IN-LENGTH PIC S9(7) COMP SYNC. 
01 OUT-FIELD PIC X. 

O01 OUT-LENGTH PIC S9(4) COMP. 

01 STATUS-BYTES PIC S9(7) COMP. 

O01 RC PIC S9(7) Comp. 


PROCEDURE DIVISION 
USING IN-FIELD, SPA, IN-LENGTH, OUT-FIELD, 
OUT-LENGTH, STATUS-BYTES, RC. 


MOVE +0 TO STATUS-BYTES. 
IF IN-LENGTH NOT = +1 
GO TO ERROR-EXIT. 
IF IN-FIELD = 'A' OR 'C' OR 'D' 
MOVE IN-FIELD TO OUT-FIELD 
ELSE GO TO ERROR-EXIT. 


VALID-EXIT 
MOVE +1 TO OUT-LENGTH 
MOVE +0 to RC. 
GOBACK. 


ERROR-EXIT. 


ADD +2048 TO STATUS-BYTES. 
MOVE +1 TO RC. 
GOBACK. 
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SUBSYSTEM INTERFACE TO 
THE EDIT UTILITY 


Whether or not Editing is required for a message type is indicated J 
in the Front-End Verb Table (BTVERB macro). EDIT is CALLed by 
INTERCOMM (if required) for high-level language subsystems. A 

A BAL subsystem CALLS the Edit Utility directly via a standard 

OS CALL statement. The message text to be edited may be in one 

of the basic formats: 


Positional -~- data items ina pre-defined sequence 
Keyword ~- data items in any sequence, each data item being 
prefaced by a 3 character identifier 
Positional Within Keyword - positional data items within 
Keyword line 


Editing proceeds field-by-field based upon the user-specified 
Edit Control Table. Data fields may be edited by INTERCOMM or 
user-coded Edit Subroutines. The result of processing by EDIT 
is a message with a standard 42-byte message header and data 
fields in one of the two basic formats: 


Fixed Format: each edited field is of fixed length in a 
predefined sequence. 


Variable Format: each edited field may vary in length and 
position in the edited result. Each edited field 
is prefixed with a one-byte identification code, 
one-byte length, and possibly a one-byte occur- J 
rence number for fields defined as repetitive in 
the ECT. 


The EDIT Utility considers a message successfully edited if 
there are no required fields (as specified by the ECT) in error 
Or omitted. Non-required fields omitted or in error are handled 
differently depending on the result format that EDIT is creat- 
ing. Figure 12-1 details EDIT logic for the combinations of 
cases. In any event, EDIT frees the storage occupied by the 
unedited messages. 


Field Type Fixed Format Result Variable Format 


Field does not appear 
in edited result 


Field appears in edited 
result, filled with pad 
character associated 

with Edit Subroutine 


Non-Required 
Field Omitted 


Field does not appear 
in edited result, the 
status byte A assoc- 
iated with the field is 
is set to X'@8s'. 


Field appears in edited 
result filled with 
X'FF's 


Non-Required 
Field in 
Error 


Figure 12-1 EDIT's processing of non-required fields omitted or 
Ln-error. 
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In the case of unsuccessful editing, Edit sends error message(s) 
to the originating terminal for each required field omitted or in 
error. If none of the required fields are omitted or in error, it 
remains the responsibility of the application program to analyze the 
edited result and perform recovery logic for any non-required fields in 
error. A conversational design approach might be used to control an 
interactive dialog with the terminal to input new data for fields 
originally entered in error. Alternatively, the subsystem may return 
to the Subsystem Controller and the operator is responsible for 
entering the entire message again. 


The Edit Utility is CALLed by an Assembler Language subsystem as 
follows: 


(symbo1] CALL EDITCTRL, (input-message,spa,0),VL,MF=(E, list) 


where: 
input-message is the address of the unedited message 
spa is the address of the System Parameter List 


0 reserves a third word in the parameter list for 
use by the Edit utility 


list is the address of the parameter list for this CALL 


On returm from the Edit Utility, register 15 contains a return 
code (binary value) indicating the results of editing as illustrated in 
Figure 12-2. A zero return code indicates the message was edited 
successfully. The address of the successfully edited message is 
returned in the first word of the parameter list. For a non-zero 
return code, a zero address also indicates the input message was not 
successfully edited. 


Code Meaning 

“i ieee Gomes en resi ieis = = 8=CC“‘CS;C~C~S;S 

“"%y. | eansacttoa-tgpe (vere). ace found ia BAle Contvol apis, (len). 

4B Vaasa ceieteaoearage-iceny cel aeciecuaceice 0° =O 

“Ae lessens cancelled ty. euseey Eeeniaal operates using CANCE. 
option 

“AG: iW hsesacscounce tied mecaise coqgueed p canee-esucte cuietea or 


in error. 


oe ee oe ee = oe ee ee re cs ee ee ce ee ee ey ee cr ee ee ee ee ee es ee ee ee ee cw ee ee es ee se os ee ee en ee es ee se ee es 


20 Unable to find end of keyword or more than 256 item codes 


Figure 12-2. Edit Utility Return Codes 
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Figure 12-3 illustrates BAL program logic for EDITing an input 
message: 


LINKAGE - - -,MSG=(R5),SPA=(R3),- - - 


e 
aid 


CLI MSGHVMI,X'@@' EDIT REQUIRED? 

BNE OKAY NO 

CALL EDITCTRL, ((R5),(R3),),VL,MF=(E,LIST) 

LTR R15,R15 

BZ GOOD 

RTNLINK - - -,RC=4 UNSUCCESSFUL 

i R5,LIST EDITED MESSAGE ADDRESS 
EQU * 


Figure 12-3 ~ EDITING an Input Message. 
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THE OUTPUT UTILITY 


GENERAL DESCRIPTION 


The OUTPUT utility provides simplified generation ( and sub- 
sequent revision) of output formats to telecommunication 
devices; the complications of teleprocessing I/0 coding are 
transparent to the individual COBOL, FORTRAN, PL/1l or BAL 
application modules. Each application subsystem can create 
messages to be processed by the Output Utility containing 
only data fields to be inserted into a predefined format 
described by a table entry accessed by the Output Utility. 
OUTPUT will in turn perform the following: 


Ls Locate the actual format specification table entry. 

2. Decide what data will go where in the format. 

3. Format the output message(s) based on any device 
dependent constraints such as line or buffer 
size and line ending sequences. 

4. Insert the necessary T/P control characters re- 
lated to the transmission of the message. 

Sie Put the actual message(s) to the Telecommunica- 
tions Interface Module (Front-End) for transmis- 
sion to the designated terminal. 


Additionally, Output will verify the operational status for 
each destination terminal and, if required, select’ an alter- 
nate terminal if specified. 


The Output Utility executes as an INTERCOMM subsystem (mes- 
Sage processing program) scheduled by the Subsystem Controller. 
It may be defined as a resident subsystem or as a subsystem 
residing in an overlay region or dynamically loaded as re- 
quired. OUTPUT is a reentrant BAL Subsystem; concurrent 
message processing is defined by its Subsystém Control Table 
(SCT) entry. 


Messages for transmission to terminals are created by applica- 
tion programs and queued for processing via INTERCOMM service 
routines. Hence, responsibility for terminal output is 
independent and asynchronous to application program message 
processing. 


The actual functions of the Output Utility for a particular 
installation are specified by coding table entries using INTER- 
COMM macros. Format specification table entries may be core or 
disk resident at the User's option. 


40 


IPN:093 4/76 


MESSAGE FORMATS PROCESSED BY OUTPUT 


Application programs preparing messages to be processed by the 
OUTPUT Utility have a choice of message text formats as 
follows: 


: Preformatted: The application program prepares a charac- 
ter string of message text ready for transmission to the 
terminal. Any terminal dependent control characters are 
the application programmer's responsibility. The OUTPUT 
Utility will perform Station Table checking to verify the 
terminal's availability, and assign an alternate terminal 
if required and defined. 


: Variable Character Text Data for Formatting: The applica- 
tion program prepares message text as a series of charac- 
ter data fields for insertion into a format described by 
an Output Format Table Entry. Each data field in the mes- 
Sage text is prefixed by 2 or 3 one-byte binary values as 


follows: 
L L O 
L E Lt E Cc 
Cc N data or C N # data 


where IC is item (or identification) code for the field 
LEN is length 
OC# is occurrence number for repetitive fields. 


The Output Format Table number (OFT#) is the first data 
item, in a variable message, following the message header. 
Data item code number 255 is reserved for the OFT# and is 
expected as a half-word binary value. 


“ Segmented Messages: The application program prepares and 
queues a series of messages of the Variable Character 
Text Data for Formatting type. This extension of the 
formatting capabilities of OUTPUT allows sequential trans- 
mission of several messages in varying formats to a par- 
ticular terminal. This facility may be used to control 
uninterrupted transmission of "pages" of a multi-page 
report to one destination terminal. 


: Control Terminal Messages: The OUTPUT Utility may be 
instructed to prefix particular error messages with a 
line of identifying information. 


Each message type is identified by control fields in the 
INTERCOMM message header. Application programs may also 
prepare messages with Fixed Format Text, Formatting Re- 
quired which are converted by the Change/Display to the 
Variable Text Format for the OUTPUT Utility. Figure 13 
illustrates Format options. 


SUBSYSTEM 


header preformatted tex 
VMI=xX'57' 


header fixed formatted text 
VMI=x'72' 

| prefix 

[conversion , CHANGE/ 

[via COBPUT , DISPLAY 

| (COBOL, | 

, PL/I) _ _. 


hesdes variable character text, 
VMI=X'5Q' formatting required 
OUTPUT 


pander | text for transmission to terminal 


FRONT 
END 


Figure 13. Format Options for messages to OUTPUT. 
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OUTPUT PROCESSING 
OUTPUT Components 


The OUTPUT Utility is customized for a particular installation 
by coding the following tables using INTERCOMM macros: 


Output Format Table (OFT): one entry for each format 
required for conversion of messages from application sub- 
systems to terminal-dependent formats. This Table is also 
used to define INTERCOMM error messages in generalized 
formats. Table entries may be core or disk resident 
depending on frequency of uSe. 


: Station Table: one entry for each terminal, This table 
is used by OUTPUT to determine status of the device for 
which a message is intended. The table is used to deter- 
Mine if an alternate device is defined, and to select the 
appropriate alternate device if the destination terminal 
is not operational. If alternate devices are not defined, 
Front-End logic is used to queue messages for non-opera- 
tional terminals or select a Front-End defined alternate 
device. 


‘ Device Table: one entry for each terminal type defining 
hardware characteristics (line length, buffer size, etc.) 
and transmission control characters required (end-of-line, 
end of transmission, etc.). 


The Output Format Table, Station Table, and Device Table are 
required, the following tables specify optional facilities of 
OUTPUT: 


Broadcast Table: defines groups of terminals with one 
Broadcast group name, allowing a message processed by 
OUTPUT with destination terminal identified (via MSGHTID 
in the message header) as a broadcast group to be routed 
to several different terminals. OUTPUT creates a separate 
message for each terminal in the Broadcast Group. 


‘ Alternate Format Table: Optionally specifies alternate 
Output Format Table entries to be utilized for those 
instances where an alternate terminal is selected as the 
destination terminal. 


‘ Batch Report Table: Indicates messages created by specific 
Output Format Table Entries are to be written to a se- 
quential disk data set and subsequently printed off-line 
by an INTERCOMM batch utility program. This feature is 
designed for multi-page output reports, and is also help- 
ful in Test Mode for analyzing usability of Output formats 
before actual terminals are installed. 
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. Format/Terminal Table: Specifies that particular Output 
Formats are to be directed to a particular terminal, 
regardless of the destination terminal specified by the 
message header. 


OUTPUT Subsystem Logic 


The OUTPUT Utility provides for simplified generation (and 
revision) of output formats to telecommunication devices; 

i.e. terminal and/or format independence for application 
subsystems. The individual application programmer determines 
only data necessary in the format and generates that appro- 
priate data in the message text to be processed by OUTPUT. 

The application program's logic then queues its message for 
the OUTPUT Utility; OUTPUT executes as an INTERCOMM Subsystem. 
To process a message, OUTPUT performs the following steps, as 
illustrated by figure 14. 


1. Determine if formatting is required. If not, do 
steps 4 and 7 only. 

2's Locate the Output Format Table specification within 
message text. 

Si Locate the OFT entry (core or disk-resident). 

4. Verify the destination terminal (perhaps select 
alternate device). 

5. Obtain storage for the formatted message and prepare 
the header. 

6. Format the output message using both the cor- 


responding Output Format Table and Variable 

Character Text data supplied in the message passed 

to the OUTPUT Module from an application program. 
7. Pass the message to the Front-End for transmission. 


Errors encountered during the processing of messages are re- 
ported by messages to the Control Terminal and/or OS Console. 


Based on the Output Format Number specified in the message 
text being processed, OUTPUT searches the Output Format Table 
for the entry in core corresponding to the requested number. 
If the table entry is not found in the core-resident table, 
the Format Number is used as an RBN (relative block number) 
to access the Disk-resident Output Format Table entries. 


The Station Table is then searched comparing the destination 
terminal identification specified in the message header 
(MSGHTID) until the correct terminal description is found. 
Once located, the STATION Table entry indicates the terminal's 
availability and alternate terminal identification. 


: If the destination terminal is available, OUTPUT proceeds. 


‘ If the destination terminal is not available, OUTPUT 
repeats its logic based upon the alternate terminal. 


: If no alternate is specified, OUTPUT proceeds (Front- 
End logic must store and forward messages for non- 
operational terminals). 
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| 


Cc 


Message into OUTPUT: 


VMI 
header 


OFT # 


variable text data, formatting required 
text 


©) 


OFT 


Figure 14. 


STATION TABLE 
(@) OUTPUT G4) 


1 be Gi Bes gd a 


DEVICE TABLE 


©) 


header | text for transmission to terminal 


C) 


Message passed to Front End 


OUTPUT Processing Logic 
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The Station Table and Output Format Table are then compared 
to further verify the terminal's ability to receive the mes- 
Sage being processed. 


Once a terminal is selected, the type of I/0 device is ob- 
tained from the Station Table and is used to index the Device 
Table to find the line length for this device. Based on the 
line length and the estimate of the number of lines for this 
format, OUTPUT obtains storage for creation of a message for 
transmission. The OFT entry is then used to produce the re- 
quired format. 


Each line format in the Output Format Table positions data 
items identified by item code. The program processes the 
item codes in the OFT one at atime. An item code of 255 
indicates that data to be inserted in the line being prepared 
comes from the OFT itself (i.e., constants, titles, etc.) 
rather than from the application program's variable character 
text data. In this case, the data from the table entry is 
moved into the output line being prepared. 


Output processes each specified line format individually. 
When a given line format is complete, OUTPUT goes on to pro- 
duce the next line format. A line format may be specified as 
repetitive, in which case the format is repeated in the mes- 
sage being produced until no further data for that line is 
found in the incoming message. OUTPUT then proceeds to the 
next line format. 


An item code other than 255 (or item codes reserved for 
terminal-dependent use), indicates that the data is to be 
inserted into the format from the message generated by 

the application program, where each text field is prefixed 
by Item Code and Length. The indicated item code in the 
OFT is located in the message developed by the application 
program, and OUTPUT moves the data into the line being pre- 
pared for transmission. If the line format being pro- 
cessed is a repetitive one, OUTPUT searches for Item Code, 
Length, Occurrence Number prefixes. The program assigns an 
Occurrence Number of one (1) to the first line prepared. 
After this line is finished, the same line format is re- 
used, this time with an Occurrence Number of two (2). This 
process continues until no additional Item Codes are found 
in the incoming message text for this line format. 


If the data found in the incoming message has a length greater 
than the field size allocated to this item in the line, OUTPUT 
saves the rest of the data and generates an overflow line 
(multiple overflows can occur). 


The above procedure is followed for every item code in the 
table for each line. At the end of each line produced for 
the report, the appropriate control characters (carriage 

return/line feed or new line) are inserted to force a skip 
to the next line based on the device type. When all line 
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formats have been completely processed, OUTPUT passes the 
complete message to the appropriate Front-End Interface 
Module. 


CONTROL TERMINAL MESSAGES 


In order to output error messages to the supervisory control 
terminal, the individual programs prepare messages for OUTPUT 
as if they were normal output messages. However, Since it is 
important to transmit these messages very quickly, and it is 
possible that the queue for the OUTPUT Module might be very 
large, there is a separate Subsystem Control Table (SCT) 
entry for messages destined to go to the system supervisory 
terminal through OUTPUT. 


The subsystem code for this portion of the OUTPUT Module is 
in the System Parameter List in the field names SPAIDCNT. 
(The INTERCOMM default code is C'N'). This subsystem code 
should be placed in the MSGHRSC field of the message header. 
The sending application module should place the control 
terminal ID into the MSGHTID field of the message header. 
The message format type should be X'50' (placed in the MSGHVMI 
field of the message header). Following the header should 
be the item codes and data for all variable items to be put 
into the message. In addition, the error message number 
corresponding to the OFT# is identified by the item code 255 
(X'FF') field in the message text. 


Tf the format mask in the Output Format Table indicates that 
the message being output is an error (i.e., mask of X'86GP), 
OUTPUT automatically adds a prefix line to the message con- 

Sisting of the sending subsystem code followed by the format 
number (converted to character form). 


CREATION AND MAINTENANCE OF TABLES USED BY OUTPUT 


The following pages describe the seven major tables used by 
the OUTPUT Module and how to create them. These are: 


din Output Format Table (OFT). 
2s Device Table. 

Sts Station Table. 

4. Broadcast Table 

as Alternate Format Table 

6. Format/Terminal Table. 

7% Batch Report Table. 


Output Format Table 
The OUTPUT Utility's formatting functions are specified by 
the Output Format Table (OFT). This table contains all in- 


Formation required to position titles, column headings, 
special terminal dependent control characters, and to locate 
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and position variable data fields in a message being processed 
into a predefined field. 


The OFT is core-resident, ina separate CSECT labelled PMIRCNTB. 
The address of the Output Format Table appears in the System 
Parameter List. Infrequently used OFT entries may be disk 
resident and dynamically loaded as required. The Table is an 
open ended CSECT, and is created and maintained by the user. 

The end of the table is indicated by four (4) bytes of hexa- 
decimal 'FF' (generated by a PMISTOP macro). 


The following INTERCOMM macros are used to create the OFT: 


‘ REPORT: a macro which defines general format specifica- 
tions (format number, number of line formats, etc.) 


: LINE: a macro which signifies generation of a format line 
and its characteristics (i.e., repetitive or not, 
constants for page overflow, etc.) 


; ITEM: a macro which defines constants or variable data 
item codes indicating the message being processed will 
be searched for data to position within the output format. 
ITEM specifies exact positioning details for each data 
field. Items referenced in the OFT but not appearing 
in the message processed will not appear in output. 
Items appearing in the message but not referenced in the 
OFT will not appear in output. 


Coding specifications for all macros are described in detail 
in Appendix C. Figure 15 illustrates general structure of the 
Output Format Table. 


PMIRCNTB CSECT 

REP1 REPORT 
LINE 
ITEM 
ITEM 


REPORT 


PMISTOP 
END 


Pagure. 15: OUTPUT Format Table Structure. 
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To add a new report to the table, just code the header and 
detail information for the new report (see REPORT, LINE, and 
ITEM macros) and insert the report in between the last report 
presently in the Table and the PMISTOP macro. Then reassemble 
and relinkedit and the new report is part of INTERCOMM. Pro- 
cedures for loading table entries on disk are discussed ina 
Subsequent section of this manual. 


The OFT entry itself may be used to insert non-standard TP 
Control characters; however, this procedure may cause some OFT 
entries to be terminal dependent and should be used with 
Caution. If TP control characters are to be included in an 
OFT entry for a buffered device, and if those control charac- 
ters are not to count as part of the buffer length, they must 
be assigned an item code of 254 in the appropriate ITEM 

macro. 


Certain terminals have, been assigned exclusive use of other 
item codes; see the section "Terminal-Dependent Considera- 
tions". 


Device Table 


The Device Table is a core-resident CSECT named PMIDEVTB 
which specifies terminal dependent characteristics for each 
device in use at an installation. The Device Table is a 
system-oriented table, and as such is described in the 
Operating Reference Manual. 


Station Table 


The Station Table is a core-resident CSECT named PMISTATB 
which describes each terminal in the installation network. 
The terminal “logical name" (5 characters) is specified in 
this table, as well as an optional alternate terminal. 

The Station Table is a system-oriented table, and as such is 
described in the Operating Reference Manual. 


The Broadcast Table 


The Broadcast Table is a core-resident CSECT named BROADCST. 
Each entry in the table defines a group of terminals which 
can be referenced by a single broadcast group name (5 char- 
acters). The Broadcast Table is a system-oriented table, 
and as such is described in the Operating Reference Manual. 


Alternate Format Table 


The Alternate Format Table is core resident in a CSECT named 
PMIALTRP. The table is created and maintained by the user. 
Individual entries in the Table are created by the use of the 
PMIALTRN macro. The end of the Table must be indicated by the 
PMISTOP macro. The location in core of the PMIALTRP CSECT is 
pointed to by a V-type constant in the OUTPUT Module. 
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Station Table 


The Station Table is core resident in a CSECT named PMISTATB. 
The Table is created and maintained by the user. Individual 

entries in the Table are created by use of the STATION macro 

(one for each terminal location). The end of the Table must 

be indicated by 4 bytes of hexadecimal 'FF', generated by the 
PMISTOP macro. The location in core of the PMISTAB CSECT is 

pointed to be a V-type address constant in the field SPASTATB 
of the System Parameter List. 


The Station Table effectively creates 5-character "logical" 
names for each terminal in the system. The STATION Table 
Structure is as follows: 


PMISTATB CSECT 
STATION TPUS=n,.... 
STATION 
STATION 
STATION 
STATION 


PMISTOP 
END 


Note that the number of station macros is defined by the first 
STATION macro, which generates a prefix to the table entries. 
In order to add a new terminal to the system, the Station 
Table must be modified by adding a STATION macro entry, and 
updating the first STATION macro to reflect the number of 
STATION macros in the table. 


Broadcast Table 


The Broadcast Table is core resident in a CSECT named BROADCST. 
The Table is created and maintained by the user. Each entry 

in the Broadcast :Table represents one broadcast group. The 
end of this Tabel must be indicated by four bytes of hexadeci- 
mal 'FF', generated by the PMISTOP macro. The location in 

core of the BROADCST CSECT is pointed to by a V-type address 
constant in the OUTPUT Module. 


The Broadcast Table is defined by the BCGROUP macro. The Broad- 
cast group name (5 bytes) is followed by a specification of the 

terminals within the group. A message destined for a broadcast 

group (MSGHTID in the header) will cause a message to be passed 

to the Front-End for each terminal in the group. 
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In the following sample Broadcast Table, two broadcast-groups 


( are defined. 


BROADCST CSECT 
* BROADCAST GROUP GGG@l 
BCGROUP GROUP=GGG@l, 


TERMS=(NYC@Gl ,NYCO2) 


* BROADCAST GROUP GGG@2 
BCGROUP GROU P=GGGG2, 
TERMS=(LAX@1,LAX#2,LAX@3) 


PMISTOP 
END 


To add a new terminal to a broadcast group, simply insert 
the terminal-ID within the current group (preferably behind 
a terminal of the same device type). To adda new broadcast 
group to the Table, simply insert the new group behind the 
last group and prior to the PMISTOP macro. In either case, 
the CSECT must be reassembled and relinkedited. 


Alternate Format Table 


The Alternate Format Table is core resident ina CSECT named 
PMIALTRP. The table is created and maintained by the user. 
Individual entries in the Table are created by the use of the 
PMIALTRN macro. The end of the Table must be indicated by the 
C PMISTOP macro. The location in core of the PMIALTRP CSECT is 
pointed to by a V-type address constant in the OUTPUT Module. 
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The following example shows how to code an Alternate Format 
Table: 


* Macro Primary OFT, device type, (alternate OFT, 
* device type,...) 
ALT1 PMIALTRN 169,1,(191,2) 
ALT2 PMIALTRN 208,2,(2801,1,282,3,293,5) 
ALT3 PMIALTRN 3928,4,(301,2,382,1) 
PMISTOP 
END 


The CSECT statement is generated automatically by the first 
PMIALTRN macro. To add a new entry to the table, code the 
PMIALTRN macro and insert it after the last entry in the table. 
Then reassemble and relinkedit the CSECT. The OUTPUT module 
then provides the ability to create different format layouts 
for the same message going to different device types through 
the use of the Alternate Format Table. The OFT number speci- 
fied by the user application program in the message is the 
primary format number. If the terminal which is to receive the 
message is a different device type than the main device type 

as specified in the Alternate Format Table, then OUTPUT will 
use the table to find an alternate format which is suitable 

for the terminal. The output message will be formatted ac- 
cording to the appropriate OFT entry. 


The Alternate Format Table is optional. Any combination of 
alternate formats is acceptable. If no Alternat Format Table 
is included, or if there is no entry for the specified format 
number, or no detail entry for the terminal device type, the 
primary OFT entry specified in the message being processed is 
used. 


Format/Terminal Table 


The Format/Terminal Table is used to associate a particular 
format with a given terminal only. Any OFT included in the 
table will generate a message to be sent to the terminal asso- 
ciated with it in the table, regardless of the destination 
terminal specified in the message header. 


This table is constructed as a CSECT named PMIRPTAB. The 
CSECT is coded with BAL constants, and must end with a 
PMISTOP macro. 


The following code outlines the construction of a Format/Term- 
inal Table: 
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PMIRPTAB CSECT 
* REQUIRED PREFIX CONSTANTS 


DC X'PBB1' 

DC AL2 (ENDTAB-BEGTAB) 
BEGTAB EQU * 
* OFT51 TO NYCO2 ONLY 

DC HL2'51' 

DC C'nyco2' 
* OFT52 TO NYCO3 ONLY 

DC HL2'52' 

DC C'NYCO3' 


EN DTAB PMISTOP 
END 


Batch Report Table 


Any report number entered in the Batch Report Table will be 
intercepted by the OUTPUT Module and written to a local se- 
quential data set for off-line printing. This sequential data 
set must be given a ddname of RPT###H and must be defined ap- 
propriately to the system (i.e., a DD card must be in the job 
Stream) as a variable length (blocked or unblocked) output 
sequential data set. 


The table consists of a string of 2 byte OFT numbers. These 
are placed in a CSECT name REPTAPE. The module must end with 
a PMISTOP macro. 


The following code outlines the construction of this table: 


REPTAPE 


PMISTOP 
END 


The INTERCOMM Utility, PRT1403, described in the Operating 
Reference Manual, may be used to print the sequential dataset 
produced. 
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SAMPLE TABLE ENTRIES 

The examples in this section are included to assist the user 
in understanding the OFT entry options for Output Utility pro- 
cessing. 


The examples are: 


: Full messages, formatting only non-repetitive lines 
(Figure 16) 


‘ Full message, formatting with repetitive lines (Figure 17) 
5 Segmented message formatting (Figure 18) 


Each example illustrates input to the Output Utility, OFT 
entry, OUTPUT formatted result. 
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catia from Application Program: 


49132, 62 {5 


i 
| 
| eas {52° | 


Output Format Table Entry: 


OFT#52 


REPORT 


LINE 
ITEM 


LINE 
LINE 
ITEM 
ITEM 
ITEM 
ITEM 
LINE 
LINE 
ITEM 
ITEM 
ITEM 
ITEM 
LINE 
LINE 
ITEM 
ITEM 


NUM=52,LINES=7 

NUM=1,ITEMS=1 
CCDE=255,FROM=5,TO=26,DATA='PARTS INVENTORY 
REPORT! 

NUM=2,ITEMS=@ 

NUM=3,ITEMS=4 
CODE=255,FROM=1,TO=12,DATA='PART NUMBER: ' 
CODE=1%,FROM=15,TO=18 
CODE=255,FROM=2@, TO=29, DATA='INVENTORY' 
CODE=29, FROM=31,T0=35 

NUM=4,ITEMS=@ 

NUM=5,ITEMS=4 

CODE=255,FROM=1,TO=12, DATA='DESCRIPTION:' 
CODE=39,FROM=15,TO=29 
CODE=255,FROM=31,T0=35,DATA='COST:' 
CODE=4% ,F ROM=37,TO=41 

NUM=6 , ITEMS=9 

NUM=7, ITEMS=2 

CODE=255,FROM=1,TO=15, DATA='RE-ORDER POINT:' 
CODE=5%,FROM=17,TO=18 


Result of Output Formatting: 


tenis nen 


PARTS INVENTORY REPORT 


PART NUMBER: (10) INVENTORY: (20) 


DESCRIPTION: G0) COST: (40) 
Nee” Nee” 
RE-ORDER POINT: (50) 


(n) indicates data item filled in from text of message pro- 
cessed by output. 


Figure 16. 


Full Message Formatting with non-repetitive Lines. 
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Message from Application Program: 


| header, 5A| FF| 62190, 33132, 04,6037, 08 (55) 1,08 01,30) | 


14,PD,91,(20)| 5D, P98, 01 ,93|1E, 08,02 (30]14 ,0D, 02,20 


| 5D, 68,02 ,(931 87, 0C 7) 8,97 (8) | 


Output Format Table Entry: 


OFT@51 REPORT NUM=51,LINES=9 


LINE NUM=1,ITEMS=1 
ITEM CODE=255,FROM=19 ,TO=21,DATA='SALES REPORT! 
LINE NUM=2,ITEMS=@ 
LINE NUM=3,ITEMS=4 , REPET=6 
ITEM CODE=255,FROM=1,TO=8 ,DATA='DIVISION' 
ITEM CODE=5%,FROM=19,TO=19 
ITEM CODE=255,FROM=22,T0=25,DATA='DATE' 
ITEM CODE=55,FROM=27 , TO=33 
LINE NUM=4 , ITEMS=@ 
LINE NUM=5 , ITEMS=3 
ITEM CODE=255,FROM=1,TO=19,DATA='SALESMAN''S NAME' 
ITEM CODE=255,FROM=14,T0=25, 
DATA='TOTAL DOLLAR SALES' 
ITEM CODE=255,FROM=28 ,TO=33,DATA='PCT OFQUOTA' 
LINE NUM=6,ITEMS=@ 
LINE NUM=7 , ITEMS=3, REPET=8 
ITEM CODE=38,FROM=1,TO=19 
ITEM CODE=29,FROM=14,TO=25 
ITEM CODE=93,FROM=28 ,TO=34 
LINE NUM=8 , ITEMS=6 
LINE NUM=9,ITEMS=3 , REPET=6 
ITEM CODE=255,FROM=1,T0=6,DATA='TOTALS' 
ITEM CODE=7 , FROM=14 , TO=25 
ITEM CODE=8 , FROM=28 , TO=34 


Result of Output Formatting: 


SALES REPORT 


DIVISION 60) DATE 65) 


SALESMAN'S TOTAL DOLLAR PCT OF 
NAME SALES QUOTA 


ee) (2 0) (93 


TOTALS (7) _@® 


eee 


(n) indicates data item filled in from text of message pro- 
cessed by output. 


Figure 17. Full Message Formatting with Repetitive Lines. 
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EMPLOYEE HOURLY WAGE REPORT 


DATE: (60) 


EMPLOYEE NAME ea WAGE 


] First 
Segment 
wages | VMI=51 
Intervening 
1 segments 
VMI=52 
This Segment 
may be repeated 
TOTAL NO. EMPL: (75) AVG HOURLY RATE: or Last Segment 
VMI=53 


n times 
n indicates data item filled in from text ot message passed 
by OUTPUT. 


Multi-Segment Message from Application Program: 


First Segqment 


VMI 
header,5l a oe ee 3C,98 (69) 
See 


[467 1c, P6[7H)] 58.85, 86 (89) 


VMI 
header,53 ak i 00,37| 4B, 95475) 


Figure 18. Full Message Formatting - Multi-Segmented Message. 
(part 1 of 2) 
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Output Format Table Entry: J 
OFT#54 REPORT NUM=54,LINES=8 

LINE NUM=1,ITEMS=1,REPET=5 

ITEM CODE=255,FROM=5,TO=31,DATA="EMPLOYEE HOURLY 

WAGE REPORT! 

LINE NUM=2,ITEMS=§, REPET=5 

LINE NUM=3 , I1TEMS=2,REPET=5 

ITEM CODE=255,FROM=1,TO=4,DATA='DATE! 

LITEM CODE=69,FROM=6,TO=13 

LINE NUM=4,ITEMS=9%,REPET=5 

LINE NUM=5,ITEMS=2,REPET=5 

ITEM CODE=255,F ROM=3,TO=15,DATA='EMPLOYEE NAME! 

ITEM CODE=255,FROM=59,TO=61,DATA="HOURLY WAGE' 

LINE NUM=6,ITEMS=8,REPET=5 

LINE NUM=7,ITEMS=2, REPET=1 

ITEM CODE=79, FROM=3,TO=27 

ITEM CODE=89,FROM=55,T0=58 

LINE NUM=8, ITEMS=9, REPET=1 


OFT#55 REPORT NUM=55,LINES=1 


LINE NUM=1,ITEMS=4,REPET=6 

ITEM CODE=255,FROM=1,TO=14,DATA='TOTAL NO. EMPL' 
ITEM CODE=75,FROM=16, TO=29 

ITEM CODE=255,FROM=59,TO=64,DATA='AVG HOURLY RATE! 
ITEM CODE=85 , FROM=66,TO=79 


Figure 18. Full Message Formatting - Multi-Segmented Message. 
(part 2 of 2) 
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ERROR MESSAGES FROM OUTPUT 


Error messages reflecting problems encountered during message 
Processing by the Output Utility are generated and queued for 
subsequent processing via the Output Utility. The messages are 
formatted according to OFT entries. Each error message is prefixed 
with identifying information: 


SEQNO (Sequence Number of message in error) 

SSC (Sending Subsystem Code) 

RSC (Receiving Subsystem Code) 

TID (Destination Terminal of message in error) 


Each error message explicitly defines the reason for rejecting 
the message being processed, for example: 


"THE FROM IS GREATER THAN THE TO FIELD" 

"REPORT NUMBER NOT IN MESSAGE" 

"RCTnnnn NOT FOUND" (OFT entry missing for nnnnn) 

See Messages and Codes for a precise listing of Output Utility 
error messages. 
OUTPUT USER EXIT 

An optional user-coded exit, USROTEDT, is available in PMIOUTPT. 


If coded, control is passed to USROTEDT after a message has been queued 
for output. Options and coding techniques are documented in Section 8 


of the Operating Reference Manual. 
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SUBSYSTEM INTERFACE TO 
THE OUTPUT UTILITY 


The OUTPUT Utility subsystem processes messages destined for 
terminals operating under control of INTERCOMM. It is respon- 
Sible for completing any device-dependent formatting require- 
ments in a message before passing it to the TP Interface for 
eventual transmission to the terminal device. It also checks 
the operational status of destination terminals. Should it 
find a destination terminal not operational, it will redirect 
messages to an alternate terminal, if an alternate terminal 
has been named in the Station Table entry for that particular 
destination terminal; otherwise the front-end will intercept a 
message to a non-operational terminal and queue it in the 
Output queue assigned to that terminal to await its avail- 
ability. 


The OUTPUT Utility also may perform report and display format- 
ting based upon specifications in the Output Format Table. 
This includes columnizing, titling, and positioning variable 
data. A message sent from an application subsystem to the 
OUTPUT Utility need consist of variable data characters only. 
Constants and spacing characters are generated from the table 
specifications and therefore are not necessary within the mes- 
Sage itself. 


The OUTPUT Utility will also facilitate the preparation of 
reports containing several different message formats, for 
example, a title page, detail pages, and a summary page. In 
this instance, an application subsystem creates multiple mes- 
sage segments where each segment may require formatting with 

a different Output Format Table entry. These message segments 
are sent one by one to the OUTPUT Utility, and it in turn will 
assure that all message segments are transmitted in the proper 
sequence and that no other messages are sent to the terminal 
until after the final segment has been sent. Multi-segment 
messages are discussed ina separate section of this chapter. 


To use the OUTPUT Utility, a subsystem creates a message header 
and text and directs the message to the OUTPUT Utility. This 
is accomplished in a COBOL or PL/I subsystem by CALLing the 
INTERCOMM system program COBPUT, in a BAL subsystem by CALLing 
the INTERCOMM system program MSGCOL. 


OUTPUT MESSAGE HEADER 
The message header may be created by copying the input message 


header to the output message header area and adjusting the 
fields shown in Figure 18-l. 
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Field Name Content 
eee ie a Se ey 


MSGHLEN Message length: 
42 plus the number of bytes of output 


message text. 


MSGHRSCH, Receiving subsystem codes: 
MSGHRSC The appropriate subsystem code (see 


figure 31) depending on the format 
of the message text. 


MSGHSSCH, Sending subsystem codes: 
MSGHSSC The code of the application subsystem 


(found in the receiving subsystem code 


fields of the input header). 


MSGHTID Terminal Identification: 
The 5-character name of the destination 
terminal. This field contains the name 
of the terminal originating the input 
message and need only be changed when 
sending a message to a different ter- 
Minal, or to a broadcast group. 


MSGHVMI Verb/message identifier: 
The indicator defining the format of 
the message text (See figure 31). 


Figure 18-l. Message header fields used by the OUTPUT Utility. 


MESSAGE TEXT FORMATS FOR OUTPUT UTILITY 


The OUTPUT Utility processes various output message formats 

in various ways as distinguishable from fields in the message 
header. The simplest is the preformatted message which requires 
no format processing. Formattable message types include two 
forms of variable field messages, those using character item 

and length codes (COBOL and PL/1) and those using binary codes 
(Assembler, COBOL, PL/1). There is also a fixed field formatting 
capability that uses the CHANGE/DISPLAY Utility. 


Except for preformatted messages, all other formats can be either 
Ssingle-segment messages or multi-segment message groups. Figure 
18-2 shows the message header fields describing the various 
message formats for single segment messages. Multi-segment 
messages are discussed separately (see Figure 18-13). 
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CHANGE/ 
DISPLAY 
TEXT PREFIX 


MESSAGE HEADER FIELDS* 
MSGHRSCH | MSGHRSC | MSGHVMI 
Se 


OUTPUT MESSAGE 
TEXT FORMAT 


Preformatted 
(Device-Dependent) 


Formatting Required, 
Variable Text - 
Character Format 
(COBOL and PL/1 only) 


Formatting Required, 
Variable Text - 
Binary Format 

(COBOL and PL/1) 


Formatting Required, 
Variable Text - 
Binary Format 
(Assembler Language) 


Formatting Required, 
Fixed Text 


*Note that whenever a character value is allowed for MSGHRSCH 
or MSGHVMI, it is the high-level language queuing routine 
COBPUT which performs conversion of the character value(s) 
to the hexadecimal value(s) expected by the Output Utility. 
Therefore, assembler subsystems must always use the hexa- 

decimal value(s). 


Figure 18-2. Message Header Specifications - Single Segment 
Messages. 
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SALES SUMMARY REPORT 


MONTH ENDING XX/XX/XX (6) 
DIVISION XXX 


BRANCH % OF QUOTA 


XXX (5) XX 


XXX XX 


SXXX. XX 


DIVISION TOTAL SXXXX. XX 


Figure 18-3. Sample display layout, showing typical item code 
numbers of variable data items. 


BUILDING MESSAGE TEXT 


Figure 18-3 depicts a sample screen or report layout showing the 
item code numbers assigned to the variable data fields. This 
layout corresponds to the sample format table and the sample 
output messages used in illustrating the various message types. 


Preformatted Text 


The message text consists of both text and device control 
characters ready for transmission to the terminal. All spacing 
and other format considerations (titles, column headings, etc.) 
are included in the message text. The OUTPUT Utility simply 
passes the message to the TP Interface. Figure 18-4 shows 

a sample pre-formatted message to generate a display or print- 
out conforming to the layout depicted in Figure 18-3. 


Formatting Required, Variable Text 


The message text consists of a string of data items to be in- 
serted into a final message structure defined in a numbered 
Output Format Table (OFT). ITEM entries in the designated 
table define the position and content of all titles, headings, 
footings, etc., and the positioning specifications for text 
fields contained in the message. Figure 18-5 depicts the 
associated Output Format Table Entry where the REPORT, LINE and 
ITEM macros describe the display format and assigned data item 
code numbers shown in Figure 18-3. 
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HEADER TEXT... J 
RSCH=K' OO", RSC=C'U', VMI=x'57'| SALES SUMMARY 


REPORT 


DIVISION XXX BRANCH 


% OF QUOTA 


Repeating 


Detail XXX SXXX.XX XX a, 
Lines 


DIVISION TOTAL SXXXX.XX XXX ~ 


A=New line x'15' 


Figure 18-4. Sample pre-formatted output message. 


Data items in the message text consist of an item code number, 
data field length count, and text field. Data items having 
the same item code number may appear more than once ina mes- 
sage. The brace in Figure 18-5 illustrates how in this case, 
a LINE entry in the designated OFT indicates that all ITEM 
code numbers within the domain of that prototype line are 

to be REPETitive. Whenever data items containing these so 
designated item code numbers appear in a message, an occurrence 
number must also appear within the corresponding text field 
immediately preceding the actual text. Data items defined 

in the OFT as repetitive require this occurrence number in the 
data field even if for some reason the data item itself were 
never to appear more than once in a message. 


The first data item in a variable message to the OUTPUT Utility 

should designate the OFT# to be used for formatting the message. 

Data item code number 255 is reserved for this use, and the 

OFT# is expected as a halfword binary value. Otherwise, data 

items may appear in any convenient sequence, because correspond- : 
ing ITEM entries in the Output Format Table control the field - 
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RPTG9899 REPORT NUM=99,LINES=9 
LINE NUM=1,ITEMS=1 
ITEM CODE=255,DATA='SALES 

SUMMARY REPORT', 

FROM=16,TO0=29 
NUM=2,ITEMS=Q 
NUM=3,ITEMS=2 
CODE=255, DATA='MONTH 

ENDING', FROM=l1, 

TO=12 
CODE=6, FROM=15,TO=22 
NUM=4,ITEMS=2 
CODE=255,DATA='DIVISION' 

FROM=1,TO=8 
CODE=17,FROM=18,TO=12 
NUM=5,ITEMS=9 
NUM=6, ITEMS=3 
CODE=255,DATA='BRANCH', 

FROM=1 ,TO=6 
CODE=255,DATA='TOTAL', 

FROM=18,TO=15 
CODE=255,DATA='% OF 

QUOTA',FROM=19, 

TO=28 
NUM=7, I TEMS=3 JREPET=Lh 
CODE=5,FROM=1,TO#3 
CODE=1f,F ROM=19,TO=16 
CODE=15,FROM=19,TO=29 
NUM=8, ITEMS=6 
NUM=9, ITEMS=3 
CODE=255,FROM=1,T0O#14, 

DATA='DIVISION TOTAL' 
CODE=18,FROM=19,TO=17 
CODE=19,FROM=19,TO=21 


Figure 18-5. Sample Output Format Table Coding (OFT #99999). 


location and sequencing in the output message. Hence, application 
Subsystems require no modification when screen or report format 
changes are required. Also several different application sub- 
systems may utilize various common OFT's. When doing this, the 
application programmer must be aware of the item code numbers 
assigned to each text field defined in the OFT's to be used. 


There are two forms of variable text messages; character and 
binary. The variable character message format varies from the 
variable binary message format in that the binary message for- 
Mat utilizes 8-bit binary item code numbers, data field length 
counts, and occurrence numbers, while the character format uses 
3-character integer fields instead, along with a special N or R 
repetition character to indicate whether or not an occurrence 
number is to be expected within the text field. The OUTPUT 
Utility, however, accepts only the one-byte binary format, and 
it is the COBPUT high level language queuing routine that 
converts the 3-character values to one-byte values and eliminates 
the repetition character. 
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Variable Character Text (COBOL or PL/1 only) 


As shown in Figure 18-6, each data item consists of a 3-integer 
item code number, 3-integer data field length count, and data 
field. The data field is further broken down to include a 
repetition character, and if the field is repetitive, an oc- 
currence or line number. Figure 18-2 indicates the applicable 
message header codes for this message format. 


[header] , , | , 4 | N [text 


IC# LEN @ 


3-byte integer Item Code (PIC '999'); 
3-byte integer LENgth (length of data plus 1 


for N or plus 4 for R and OC#); 
l-byte repetition character 'R' or 'n' to 
indicate Repetitive or Not; 
3-byte integer Occurrence number. 


Figure 1876. Illustration of variable character message format. 


As shown in figure 18-7, the first data item in a variable char- 
acter message to the OUTPUT Utility should consist of: 


1. Item code of 255; 

2 Length (003); 

3. N; 

4. Fixed binary (15) Output Format Table entry 
number (OFT#). 


42-byte header | F2 F5 F5 |FS FO F3 | D5 | BH 63 


Item Code Length Format 
255 3 N 99 


Figure 18-7. Illustration of variable character message showing 
OFT# field. 


Figure 18-8 shows a sample variable character format message to 
generate a formatted message conforming to the layout depicted in 
Figure 18-3. Remember that the data items may appear in any 
sequence convenient to the programmer; they need not be grouped 
Or sequenced as shown. 
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HEADER 


Heading Data 
date 
DATA 


DOSOOH7TRAOH1LXXX Bg Dg DISPPSRPP1IXX 
@oc#br @oc# total GlOc #3 


IC #LE DATA | IC#HLE DATA IC#LEN DATA 


Repeating BISPPGERHAH2XX 
Detail @oc#br | q 
Data - DATA IC#HLEN 


Footing Data 


Item Code defined in output format table entry. 
Length of data. 

N indicates Non-repetitive data items, 

R indicates Repetitive data items. 

Output Format Table number. 

Occurrence number for Repetitive items. 


Figure 18-8. Sample variable character format output message. 
Variable Binary Text (COBOL, PL/1, Assembler) 


As shown in Figure 18-9, each data item consists of a one-byte 
binary item code number, a one-byte binary data field length 
count, and data field. In the case of repetitive data items, 
the data field contains a one-byte binary occurrence number 
immediately preceding the text. Figure 18-2 indicates the 
applicable message header codes for this message format. As 
with variable character text, one of the data items in the 
message text must be item code:255, length:2, data:OFT#. 


[header | 01 | 04 [{[ text | va | 8 | 1 | text... 


Figure 18-9. Illustration of variable binary message format. 
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Formatting Required, Fixed Field Text 


The message text consists of adjacent fixed length text fields 
Similar to the layout of a logical record in a data set. The 
fields may be character, binary, or packed decimal. The mes- 
Sage is operated upon by the CHANGE/DISPLAY Utility to convert it 
to a variable binary format message as described above. A 

Format Description Record must be created for this fixed format 
in order for the CHANGE/DISPLAY Utility to build a corresponding 
item code, length and data, variable binary format message and 
pass it on to the OUTPUT Utility. 


The message text is prefixed by 12 characters: 


1-8: 1 to 8 alphanumeric characters, left adjusted. 
The Change Table will be searched for a match 
on this field to find the appropriate Format 
Description Record. 


9: § if this data is to become a single segment 
message for OUTPUT. 


19-12: OFT number to override FDR default value. 


Figure 18-10 illustrates the fixed field message format. The 
length field in the header must include the length of the 
fix. Figure 18-2 indicates the applicable message header 
for this message format. 


pre- 
codes 


42-byte header FRMTREC1@973 FIELDAFIELDBETC. 


| PREFIX | DATA | 


FRMTRECL The Fixed Format Name associated 
with the Format Description Record as 
listed in the Change Table, 


p Indicates a single segment message, 


The Output Format Table entry 
number (to override RPTNO in FDHDR). 


Figure 18-10. Fixed field message illustration showing 
prefix field. 


Figure 18-11 shows a sample fixed field message to generate a 


formatted message conforming to the layout depicted in Figure 18-3. 
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HEADE TEXT-PREFIX 


FORMNAME ShbB/ 3 


Heading XXXXXX XX 


Data date div 


Footing XXXXXX XX 
Data total % 


PxxX Of XxXxxX [| xxi} 


br total % 


Repeating 


Detail Exxx  [ XXxXXX | Xx/} 


Data br total % 


br total % 


Figure 18-1ll. Sample fixed format output message. 


The first eight characters of the l2-character text-prefix 
identifies the name of the Format Description Record in which 
each of the individual text fields is defined. This includes 
defining every item code, length, and data type. It is 

used by the CHANGE Utility in converting the fixed format 
text fields to variable binary format data items for the ouT- 
PUT Utility. The remaining characters indicate the message 
segment number and overriding Output Format Table entry 
number (OFT#), if any. 


Notice in Figure 18-11 that the repeating detail data appears 
at the end of the message, instead of between the heading and 
Footing lines. This is because the CHANGE Utility requires 
that all repeating data items must appear as a group at the 
end of the message or record to be converted for the OUTPUT 
Utility. Figure 18-11 shows the sample Format Description 
Record (FDR) and Change Table entry needed by the CHANGE 
Utility to convert the sample fixed format message shown in 
Figure 18-l1l. 
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DES £DPH1 

FORMNAME NAME=FORMNAME, RPTNO=99,FIELDS=7, 
REPSZ=14 

DATE OFSET=$, LEN=8 , CODE=6, NAME=DATEX 

DIVISION OFSET=8, LEN=3,CODE=17,NAME=DIVSN 

DVTOTDOL OFSET=11,LEN=8,CODE=18,NAME=TOTDL 

DVTOTPCN OFSET-19,LEN=3,CODE=19,NAME=TOTPC 


BRNCHNUM OFSET=22,LEN=4,CODE=5,NAME=BRNCH, 
FLD=REPET 

BRNCHTOT OFSET=26, LEN=7,CODE=18,NAME=BTOTX, 
FLD=REPET 


BRNCHOTA OFSET=33,LEN=3,CODE=15,NAME=BQOTAX, 
FLD=REPET , 


DC CL8'FORMNAME' NAME corresponding 
to DES#6#G1 

Dc A (BD) RBN § on DES#/4H= 
DES £PHH1 


Figure 18-12. Sample Format Description Record Coding 
(DES#G@GG1l) and Change Table Entry. 


MULTI-SEGMENTED MESSAGES 


When a subsystem produces a report with many different detail 
lines, it may be constructed as a multi-segment message. It 
requires formatting and can be either variable character or 
fixed length text. A multi-segment message, then, consists 

of two or more logically related INTERCOMM messages (header 
followed by text) directed to a single terminal without inter- 
reuption. 


The responsibility of the OUTPUT Utility here is more complex. 
It must provide formatting of each segment of a message trans- 
Mitted to a single terminal under exclusive control and upon 
completion of transmission, release the terminal exclusive use 
status. Again to determine the message format OUTPUT analyzes 
the MSGHRSCH, MSGHRSC and MSGHVMI fields of the message header. 
Each message segment has its own 42-byte message header. The 
contents of the fields to be adjusted by the application sub- 
system are diagrammed in Figure 18-713. Since an OFT# is 
specified for each segment of the message, the text formatting 
can be controlled by different OFT entries. 
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MESSAGE HEADER FI * 
OUTPUT MESSAGE : eae ak CHANGE/ 


| 
TEXT FORMAT | MSGHRSCH MSGHRSC MSGHVMI DISPLAY 
(see note PEST “PREF LX 
| below) BYTE 9 


N/A 


Variable Text - 
Character Format 
(COBOL and PL/1) 


Variable Text - 
Binary Format 
(COBOL and PL/1) 


Variable Text - 
Binary Format 
(Assembler) 


Fixed Text 


*Character values for MSGHRSCH or MSGHVMI are converted by 
COBPUT to the expected hexadecimal values. Assembler sub- 
systems must use the hexadecimal values. 


The VMI value of Change/Display Prefix Byte 9 indicates seg- 
ment type: 


X'51'/C'1l' indicates header segment and causes the OUTPUT 
Utility to select only non-REPETitive items, as coded in 


the corresponding OFT, from the message text; 


X'52'/C'2' indicates intermediate segment and selects only 
REPETitive items from the message text; and 


X'5c'/c'4' indicates intermediate segment and selects only 
non-REPETitive items from the message text. 


X¥'53'/C'3' indicates final segment and selects only non- 
REPETitive items from the message text. 


Figure 18-13. Message Header Specifications - Multi-segment 
Message. 
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The OUTPUT Utility accomplishes the processing of a multi- 
segment message in conjunction with the DVASN service routine. 


When the COBPUT queuing routine first recognizes a multi- 
segment message for OUTPUT (VMI=X'51'), the INTERCOMM system 
program DVASN is called to assign the destination terminal 
named in the message header to a "multi-segmented-message- 
transmission-in-progress" condition. Once this assignment 

is made, the OUTPUT Utility will accept only intermediate 
segments (VMI=X'52' or X'5C') for that device until a final 
message segment (VMI=X'53') for that service is processed. 

For this reason, the COBPUT routine requires that the name of 
the field containing the binary OFT# in the first message of a 
multi-segment message group be named in the otherwise optional 
third parameter, OFT#. 


A BAL application subsystem must CALL the DVASN subroutine to 
obtain exclusive use of a terminal for a variable character 
text multi-segment message, before queuing the message for 
transmission to OUTPUT via MSGCOL. DVASN will assign the 
destination terminal indicated in the message header, to a 
"multi-segmented-message-transmission-in-progress" condition. 


When Fixed Format Text is used, the CHANGE/DISPLAY Utility 

assumes responsibility for the CALL to the DVASN routine to 
"assign" the terminal for the duration of segmented message 
transmission. The CALL to COBPUT, then, is made with only 

two parameters as usual. 
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SEGMENTED MESSAGE OUTPUT TERMINAL ASSIGNMENT (DVASN) 


The DVASN mesSage processing service routine has been referenced 
previously in this text in conjunction with the OUTPUT Utility. 
DVASN is called by a subsystem to obtain exclusive use of a 
terminal for the purpose of transmitting a multi-segment message 
without interruption. The DVASN subroutine must be CALLed before 
queuing the first segment of a multi-segment message via MSGCOL 
for formatting by OUTPUT. 


The coding format for calling DVASN is: 


[symbol] DVASN, (cmp,spa,term,oft,ret), MF=(E,11iSst) 


Where: 


cmp is the address of a field containing the 
number of the company or division being 
serviced. (2 byte, binary). 

spa is the address of the System Parameter List. 

term is the address of a field containing 
character MSGHTID destination terminal 
name field in the message header. 

oft is the address of a field containing the OFT 
number of the format about to be started. 
(2 byte, binary). 

ret is the address of a five byte field in 
which to return the terminal ID (CCCNN) 


As a result of this call, DVASN will locate and assign a 
terminal to the subsystem and designate it as a “multi- 
segmented-message-transmission-in-progress" condition in 

its respective entry in OUTPUT's Station Table. This action 
thus prevents other messages from being transmitted to the 
designated terminal until its busy status is freed by OUTPUT. 
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THE CHANGE/DISPLAY UTILITY 


GENERAL DESCRIPTION 


The CHANGE/DISPLAY utility provides predefined transactions 
to access on-line files from remote locations. A terminal 
Operator can trigger the retrieval of one record at a time 
from a user file. All or part of the information accessed 
may be displayed back on the remote device (DSPL verb). 
DISPLAY data will appear in character format according to an 
Output Utility OFT. Alternatively, one or more of the data 
fields in an accessed record can be altered (CHNG verb). The 
record as CHANGEd is. then Written back to the user file. 


For the processing of CHNG and DSPL verbs, -CHANGE/DISPLAY sup- 
ports BDAM, ISAM, and VSAM files. In each case, records 

must be in fixed format. BDAM files are accessed by relative 
block number (RBN); ISAM files are accessed by key. VSAM 
files are accessed by key, via the File Handler logic for VSAM 
compatibility with ISAM. Individual fields within a record may 
contain binary, packed, or character data. 

Terminal input transactions are entered in key word format, 
and processed by the EDIT Utility. A file ddname and a key 
(or RBN) are entered, and the specified record is retrieved. 
If DSPL was entered, the data accessed is formatted as a mes- 
sage for the OUTPUT Utility. In addition to file ddname and 
key, a CHNG transaction specifies fields to be altered. Re- 
placement data is indicated for each field entered. The 
record in core is altered as specified and then rewritten. 

A message designating completion of processing, successful 

Or unsuccessful is formatted for OUTPUT in this case. 


The CHANGE/DISPLAY Utility also processes fixed format data 
passed from an application subsystem. (No user data base is 
accessed in this case.) Such intersubsystem messages are 
reformatted as new messages for the OUTPUT utility. This 
application program technique is referred to as Fixed Format 
Text, Formatting Required in the Section "Using the Output 
Utility" in the Programmer's Guides. The application pro- 
grammer is not concerned with item code/length prefixes for 
data fields; thus the potential for program errors is reduced. 
The text of such an intersubsystem message simulates a fixed- 
format file record. Processing bypasses access of a user 
file and continues as though a DSPL transaction had been 
entered. 


The CHANGE/DISPLAY utility is entirely table driven. The 
following table entries (illustrated in Figure 19) are re- 
quired: 


6l 


CHNG 


DSPL Verbs described in Front-end Verb Table 


INTERSUBSYSTEM 


Fixed 


Format 
Message 


UTILITY 


Baas 


CHANGE/ OUTPUT 
DISPLAY UTILITY 
Key Table 


(BDAM files 
only) 


TERMINAL 
Output Msg. 


ae 


Format User File Change 
Descrip. Data Table Table 
Records File 


Figure 19. Functional Components of CHANGE/DISPLAY. 
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l. Entries for CHNG and DSPL in the Front-End Verb Table. 

2. Entries for CHNG and DSPL in the EDIT Control Table. 

3. Entries in the File Table for each on-line file to be 
accessed. 

4. A Format Description Record (FDR), a disk resident 
table entry for each user file to processed; and/or 
each format of intersubsystem message to be processed 
for OUTPUT. 

one An Output Format Table entry for each display format 
to be produced. 

6. A Change Table entry for each format of intersubsystem 
message to be processed for OUTPUT. 

7. A Key Table entry for each user-coded key editing 
routine. 

8. A Pattern Table entry for each editing pattern speci- 
fied in the Format Description Records. 


Some installations may not wish to exercise all CHANGE/DISPLAY 
options. In such cases, not all of the above table entries 
are required. For instance, CHNG transactions may not be de- 
Sired; CHNG entries would then be omitted from the Front-End 
Verb Table and the EDIT Control Table. Another installation 
might not wish to process intersubsystem messages for OUTPUT; 
in such cases, the FDR and Change Table would be omitted. In 
Other words, the table entries supplied will determine which 
CHANGE/DISPLAY options are available. 


CHANGE/DISPLAY executes as an INTERCOMM subsystem and may be 
defined as resident, overlay region, or dynamically loaded. 
TERMINAL INPUT MESSAGE FORMATS 

For a DISPLAY transaction, a DSPL verb is entered at the 
terminal. For a CHANGE transaction, a CHNG verb is entered. 


The explicit formats of these verbs are detailed below. 


DSPL Verb 


DSPL A (Display verb) 
FLN XXXXXXXX A (File ddname) 


KEY XXXxX. (Key or record to be displayed) 
RPT XXX A (Output format number) 
END O (End of message) 


The file name entered following FLN must: 


die Be defined to INTERCOMM by a DD card in the execution 
JCL. 

2% Correspond to an entry in the File Table. 

3. Be defined:'by a Format Description Record. 
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Data entered following KEY will be one of the following: 


1. Actual key for an ISAM file. 
2. Relative block number (RBN) for a BDAM file. 


The EDIT utility passes these keyword fields through Edit Sub- 
routine $: field length is determined; no conversion of the 
data. CHANGE/DISPLAY will pass the key field through its own 
edit processing. 


The RPT parameter is optional. If included, the number sup- 
plied will override the default OFT number in the FDR. This 
option might be used to allow certain terminals to display more 
information than others. For instance, a customer file might 
contain names, addresses, and credit information. All terminals 
in the system are to have access to names and addresses. Only 
terminals in the credit office are to have access to credit in- 
formation. The standard OFT number specified in the FDR would 
format only name and address for OUTPUT. Operators of credit- 
office terminals would be told an overriding number to enter. 
This second OFT number would format name, address, and credit 
information for OUTPUT. Of course, every format number 
(whether from FDR or RPT data) must correspond to an entry in 
the Output Format Table. 


CHNG Verb 


To update a record, the following transaction is keyed in at 
the remote location: 


CHNGA (Change verb) 
FLN XXXXXXXX A (File ddname) 
KEY XXXX.<&. (Key of record to change) 
FDN XXXXX A (Name of field to change) 


VRY XXXX.... 
DTA XXXX.... 


* 
* 


(Verify data) 
(Change data) 


A 

SKY XXXX....A (Secondary key) 
A 
A 


ENDO). (End of message) 


The FLN and KEY parameters are subject to the same restric- 
tions as are the corresponding DSPL parameters. 


In the FDN parameter, the operator enters a field identifier 
of up to five characters, indicating the name of the field to 
be changed. 


The SKY parameter is optional. It is used to supply a second- 
ary key for use in searching groups of repetitive fields to 
locate a particular field to CHANGE. When the SKY data matches 
the repetitive field group secondary key, the associated FDN 

is CHANGEd. 
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The VRY parameter should eco the data actually in this 
field in the record. The FDR may specify that verification 

is optional; in such a case, the parameter may be omitted from 
input. If VRY is entered, CHANGE/DISPLAY will verify the 
existing data before proceeding. 


Actual replacement data is entered following the DTA key- 
word. (Both DTA and VRY data are edited in accordance with 
FDR specifications; only after editing are they applied 
against the actual file record.) For VRY and DTA, the user 
May wish to enter blanks from the terminal. However, blanks 
will be eliminated from the message during processing. If 
verification of a blank field is desired, the operator should 
enter: 


VRY PMIBLNK 
To blank out an existing character field, enter: 
DTA PMIBLNK 


The parameters FDN, VRY, and DTA are repetitive. Thus, as 
many fields in a record as desired can be altered via one 
CHNG transaction. Note, however, that there are special con- 
siderations when SKY or VRY parameters are omitted. EDIT, 

in processing the transaction, will assign occurrence numbers 
to repetitive input items. The first appearance of a repeti- 
tive item will be assigned occurrence number 1; the second, 2; 
and so forth. CHANGE/DISPLAY requires identical occurrence 
numbers for corresponding FDN, SKY, VRY, and DTA parameters. 
VRY or SKY may be omitted for one FDN entry but included in 

a subsequent one. In such a case, correspondence of occur- 
rence numbers would be lost; to overcome this difficulty, a 
special input configuration is provided. To force an out-of- 
sequence occurrence number, the following may be entered: 


VRY(n,data) or SKY (n,secondary key) 
where n is the desired occurrence number. This facility is 
illustrated in the following CHNG transaction: 


CHNG A 

FLN FILEA A 

KEY 25 A 

FDN ADDRA (occurrence 1) 

DTA 475 BROADWAY A 

FDN city A (occurrence 2) 

VRY (2,NEWARK) A (force occurrence of 2) 
DTA NEW YORK A 


FDN CREDT A (occurrence 3) 

SKY (3,TYPEA) A (force occurrence of 3) 
VRY (3,59992) A (force occurrence of 3) 
DTA 199992 A 

FDN MANGR A (occurrence 4) 

DTA PMIBLNK A (blank out MANGR field) 
END © 
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RECORD FORMATS 


Record formats processed by CHANGE/DISPLAY refer to either 
actual data records on a user BDAM or ISAM file or "pseudo 
records" representing fixed format fields of message text 
from an application subsystem to be converted to the appro- 
priate "variable character text, formatting required" for 
the OUTPUT Utility. In either case the following conven- 
tions are required: 


is records are fixed length 

2% each data field may be unique in character, packed 
decimal, or binary form, or 

3. the record may consist of a fixed number of unique 
header fields followed by a variable number of 
repetitive groups of fields. If the number of 
repetitive groups is not maximum for the record, 
the trailing portion contains high-value (X'FF') 
pe ie 


Figure 20 illustrates record formats; note that intersubsystem 
messages also include an additional 54 bytes prefixed to the 
record format illustrated for the standard 42 byte INTERCOMM 
message header plus 12 bytes of information reguired for CHANGE/ 
DISPLAY processing. 

No Repetitive fields in Record: 


fieldl | field2| field3] - - - - - -]| (fieldn) 


Repetitive Fields in Record: 


fieldl | field2| field3 | field4a| field5a| field6éaj field4b 
header portion repetitive group 
(optional) 


“Ffield5b | field6b| field4c field5c| field6cj] FFFFFFFFF 
hi-value fill 


Figure 20. Record Formats supported by CHANGE/DISPLAY 


For ISAM files, the key will be converted according to the 
field type specification in the FDR. If a key consists of 
several fields, they must be entered in the same order as the 
FDR description of key fields. Thus, an ISAM key might con- 
Sist of: 


1. A two byte alphanumeric field. 
2s A four byte binary field. 

3. A three byte numeric field. 

4. A six byte packed field. 


Assume that a particular key on the file appeared as follows: 
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1 


22 BO OP G1 DO £6 22 06 63 SF 
2 4 


3 


The corresponding field descriptions in the FDR must appear 
in the identical sequence. To display a record with the above 
key, an operator would enter: 


DSPL A 
FLN ddname A 


KEY AA/1/5/35 A 
END © 


The RBN for a BDAM file, of course, would not be defined in 

the FDR. The supplied key is simply converted to binary, unless 
the user supplies a conversion routine. The (/) slash character 
must be part of the key supplied to CHANGE/DISPLAY and therefore 
cannot be used as the Edit Separator Character. 


CHANGE/DISPLAY PROCESSING 


All messages for CHANGE/DISPLAY enter the module at the same 
point. A check is made to determine whether the message is a 
CHNG or DSPL verb. If it is, the processing described under 
"Common Processing for CHNG and DSPL Verbs" is performed. 
Otherwise, the processing described under "Processing of 
Fixed Format Messages for OUTPUT" is performed. 


Common Processing for CHNG and DSPL Verbs 


The first program step for a CHNG or DSPL verb is a CALL to 
EDIT. The EDIT Control module is driven by the entries in 
the EDIT Control Table. If EDIT rejects the incoming mes- 
sage, the sending terminal is notified and processing is 
discontinued. 


Next, the File Table is searched for the file name entered 

at the terminal. If no entry is found, the remote location 
is notified and processing is terminated. If there is a file 
table entry, it will contain: 


5 Record number of Format Description Record (FDR) for 
this file. (The FDR describes the detail character- 
istics of every data field in the file record.) 

2. Type of user file to be accessed (BDAM or ISAM). 

ci Amount of dynamic core required for retrieval of one 
block from the user file. 


The FDR is next retrieved from disk. This is accomplished 

via the File Handler; a BDAM READ is issued with an RBN based 

on the record number in the File Table. An I/O error or record- 
not-found condition will generate an error message and process-— 
ing will be terminated. 
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The file ddname given as input is now compared to that appearing 
in the FDR. A not equal condition indicates an error in either 
the File Table or the FDR'; processing is terminated. 


The FDR is now checked to determine that editing is required 
On the incoming key. Standard editing options are: 


: Editing of key elements based on FDR detail specifications 
(ISAM keys). 


; Conversion of entered data to binary (BDAM RBN's). The 
user also has the option of supplying his own BDAM key 
editing routine. 


The edited key is returned to CHANGE/DISPLAY. 


The next step is to retrieve the User File record specified 
by the input message. The amount of storage indicated in the 
File Table is obtained. The type of file is checked, and an 
appropriate CALL to the File Handler is jssued. An I/O error 
Or record-not-found condition will produce a message and 
cause termination of CHANGE/DISPLAY processing. 


If a record is retrieved successfully, a check is made whether 
DSPL or CHNG WAS ENTERED. From this point on, processing 
differs. If DSPL, the action described under "Creating a 
Display Message" is taken. If CHNG, the action described 
under “Update Processing for CHNG" is taken. 


Processing of Fixed Format Messages From Application Programs 


Intersubsystem messages with fixed format text to be processed 
for OUTPUT bypass the CALL to EDIT, as identified by VMI of 
X'72' in the message header. The 12-byte CHANGE DISPLAY prefix 
provides information required to convert the fixed format text 
to the appropriate message for the OUTPUT Utility. 


The message format, then is: 


fixed format text 


refer to Figure 20 


42 byte INTERCOMM header 


bytes 1-8: Format identifier 

byte 9:segmented message identifier 
(see Figure 24) 

bytes 10-12 Output Format Table Number 


The Change Table contains a record number of an FDR corresponding 
to this particular message format as identified by the format 
identifier. The table itself consists of a series of associated 
identifiers and FDR record numbers. 


The FDR is next retrieved, as it would have been for a DSPL 

or CHNG transaction. The "file name" in this FDR will actually 
be the identifier supplied in the intersubsystem message; no’ 
user file is accessed. From this point on, processing contin- 
uses as it would for a DSPL verb. This procedure is described 
immediately below. 
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Creating a Message for the OUTPUT Utility 


At this point, CHANGE/DISPLAY has a fixed-format record in 
core. This may be either an actual file record or data sent 
from an application subsystem. There is also a Format Bescrip- 
tion Record in core that describes the fixed format record. 

The FDR indicates how each data field in the record is to be 
edited for OUTPUT. 


For either a DSPL verb or an intersubsystem message, core 

for a message for OUTPUT is obtained. In this area, the user 
file record (or data from an intersubsystem message) is for- 
matted. This processing follows: 


il A Message Header for OUTPUT is constructed. 

2% An OFT number (item code 255 in message for OUTPUT) 
is assigned. This number is specified by the FDR, 
unless a substitute number has been indicated with 
a DSPL verb via the optional RPT parameter. Or, for 
intersubsystem messages, overriding report numbers 
appear in the message prior to the actual data to 
be displayed; in this case, blank or zero indicates 
that the FDR OFT number is to be used. 

3% Data fields are now processed one at a time in the 
following manner: 

a) Binary and packed fields are converted to 
character. 

b) Editing specified in the FDR is performed 
(dollar, date, etc.). 

c) Necessary padding or truncation (if allowed 
by FDR) is effected. 

dad) Item code and length is prefixed to the data 
item. 

e) For repetitive fields, an occurrence number is 
also prefixed to the data. 

£f) If invalid data is found in any field being 
edited, the output field will contain the word 
"INVALID". 

4. The new message is queued, via Message Collection, 
for OUTPUT. 

- 5. Standard INTERCOMM housekeeping (i.e., freeing core, 
RELEASE of files, etc.) is performed. CHANGE/DISPLAY 
then returns to the Subsystem Controller. 


Update Processing 


If the incoming message has been a CHNG verb, the following 
steps would be taken at this point: 


al FDR detail description for first field to be altered 
is located. This search compares field identifiers 
from the input message with those coded in the FDR. 
A no-~match generates an error message. Steps 2 
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through 4 will be performed only if verify data is 

Supplied. The FDR specifies whether verification is 2 

required. If it is required, failure to provide 

verify data will cause an error. If it is not re- 

quired, steps 2 through 4 are taken only if the VRY 

keyword was entered for this field. 

a Verify data of the input message is translated to the 
format indicated for this field in the FDR. 

3s Translated verify data is compared to the field in 

the file record. 

4. If (3) compares not equal, "VERIFY REJECT" message is 
sent and processing terminates. 
5. Change data is translated to the format specified in 

the FDR detail segment. 

6. Translated change data is placed in the file record, 
overlaying existing data. 

7. A check is made to determine whether more data fields 
are to be changed. If so, processing repeats from 

(1) above. 

8. When all change fields have been processed: 

a) A test is made to determine whether a User Change 
Exit has been included in the system. (Details 
below.) If so, control is passed to it. 

b) The record is updated via the File Handler. 

os A message stating whether the change had been suc- 

cessful or not is formatted for OUTPUT. Required 

housekeeping is performed. Return to the Subsystem Con- 

troller is effected. > 


CHANGE/DISPLAY TABLES 


Tables for the CHANGE/DISPLAY Utilities are generated via 
INTERCOMM macros. The table entries required for CHANGE/ 
DISPLAY processing are: 


‘ Entries for CHNG and DSPL in Front-End Verb Table: Omis- 
sion of either entry will effectively prevent processing 
of the omitted verb. 


‘ Entries for CHNG and DSPL in the EDIT Control Table: 
Omission of either entry will prevent EDIT processing of 
the transaction type. If verb is left out of the Front- 
End Verb Table, leave it out here as well. The coding 
of ECT entries for DSPL and CHNG is detailed later. 


‘ Entry in File Table for each on-line file to be accessed: 
In addition to entries for CHANGE/DISPLAY user files, 
there must be an entry for the Format Description File 
itself; and an entry for the Output Format Table File, if 
any Output Format Table entries reside on disk; and an 
entry for the EDIT Control Table File, if any ECT entries 
reside on Disk. Construction of the File Table is dis- " 
cussed fully below. J 
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” Format Description Record (on disk) for: Each user file 


é to-be processed by CHANGE/DISPLAY, and/or each format of 
intersubsystem message to be processed for OUTPUT. The 


method of constructing individual FDR's and of loading 
them onto disk is described later. 


, Output Format Table Entries: For each message to be 
produced by CHANGE/DISPLAY, there must be an entry in 
the Output Format Table. In other words, there must be 
an OFT entry for each format number specified in the FDR's; 
and/or each format number to be entered as a RPT para- 
meter of a DSPL verb; and/or each format number to be 
specified in a fixed format message for OUTPUT. par- 
ticular note should be made of the following facts: 

1. CHANGE/DISPLAY will create a message for OUTPUT 
containing every data item from the processed 
record. When item codes supplied in the message 
to OUTPUT are not found in the OFT entry, they will 
be ignored. Hence, the design of the OFT will de- 
termine what portion of the supplied data is to 
be displayed. . 

2. Records with repetitive field groups will be for- 
matted for OUTPUT with occurrence numbers corres- 
ponding to the sequential position of each re- 
petitive item. To output such items, repetitive 
lines must be defined in the OFT entry. 


‘ Change Table entry: for each fixed format message to be 


7 processed for OUTPUT. Creation of this table is fully 
documented later in this text. 

‘ Key Table entry: for each user-coded key editing routine. 
Specifications for construction of this table are included 
in the discussion below. 

3 Pattern Table entry: for each editing pattern specified 
in the format Description Records. This table is described 
below. 

Edit Control Table Entries 

If the DSPL verb is to be used, the following entry must appear 

in the EDIT Control Table: 

DSPL,71,256,3 
FLN ,£$1,68,088,16006111 
KEY ,02,66,255,16620G11 
RPT ,$3,02,£62, 666968111 
¢ Note should be taken of the following characteristics of the 
DSPL entry in the ECT: 
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; The VMI code (2nd parameter of VERB macro) must be 7l. 
After EDIT has been CALLed, this VMI will be the only tag S 
identifying the message. (Note that CHNG has a VMI of 72, 
a fixed format message for OUTPUT has a VMI of 72. Choices 
of program paths within the CHANGE/DISPLAY utility are 
based on tests of the VMI.) 


; The FLN and KEY parameters are passed through EDIT sub- 
routine 9. This subroutine will assign item code and 
length but will not perform any conversion of incoming 
data. Note that a fixed length of 8 is forced for the 
FLN field. (Bit 5 of the bit string of the PARM macro is 
on.) Search of the File Table will be based on the 8 char- 
acter file ddname returned from EDIT. A file ddname of 
less than 8 characters will be padded on the right with 
blanks. Conversion of data supplied with KEY will be 
done within CHANGE/DISPLAY. A fixed length is not forced 
for KEY. (Bit 5 of bit string is off.) 


. The RPT parameters must be indicated as optional. (Bit @ 
of the bit string is off.) This incoming paramter is 
passed through EDIT subroutine 2:(if RPT is entered). Sub- 
routine 2 will convert the supplied parameter to binary; 

a length of 2 is forced. Thus, EDIT puts the format 
number, if supplied, into the form required for the 
message to OUTPUT. 


: Truncation is not allowed for any of the incoming para- } 
meters. (Bits 6 and 7 are both on in the bit string.) 


: Item codes 1, 2, and 3 must be assigned, respectively, 
to the FLN, KEY and RPT parameters. (Do not code a 255 
for RPT: CHANGE/DISPLAY expects a 3 and will replace 
it with 255 when building the message for OUTPUT.) 


If the CHNG verb is to be used, the following entry must appear 
in the EDIT Control Table: 


CHNG,7$,256,6 

FLN ,£1,99,668 ,18866111 
KEY , $2,00,255,1 0666611 
FDN , $3,98,665,16961111 


SKY ,$4,68,255,80661611 
DTA, $5,0%,255,16661611 
VRY,£6,62,255,08001611 


The following characteristics of the ECT entry for CHNG should 
be noted carefully: 


‘ The VMI code must be 728. : 
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é The FLN and KEY parameters are identical to the cor- 
responding parameters for DSPL. Comments on these para- 
meters following the DSPL verb ECT apply here as well. 


: FDN and DTA are required (bit @ of the bit string is on); 
SKY and VRY are optional (bit 9 of the bit string is off). 
Note, however, that VRY will be logically required if so 
flagged in the FDR. FDN, SKY, DTA, and VRY must all be 
tagged as repetitive. (Bit 4 of the bit string is on.) 

FDN must be forced to a fixed length of 5. (Bit 5 is on.) 
The search of FDR detail segments will be based on the data 
entered following this keyword. 


; Truncation is not allowed for any of the incoming para- 
meters. 
. All parameters are passed through EDIT subroutine @. 


DTA, VRY, and SKY information will be converted later 

by CHANGE/DISPLAY. This conversion will be based on the 
description of the particular field in the FDR. Normally, 
the above ECT entries would be included during the initial 
installation of INTERCOMM. In some cases, the CHANGE/ 
DISPLAY utility may be added to an existing installation. 


The File Table 


The File Table must contain an entry for each user file to be 
accessed by CHANGE/DISPLAY. It must also contain an entry for 
the Format Description File (DES##@). (Creation of Format 
Description Records is discussed later in this section.) In 
addition, the Output Format Table may have some or all of its 
entries on disk (file ddname RCTG@#G). Similarly, the EDIT 
Control Table may have all or some of its entries on disk 
(file ddname VRBYPZD). Loading Utility Table Entries on Disk 
is detailed in a later section. These files, if included in 
the system, must also have entries in the File Table. 


User files that will not require CHANGE/DISPLAY processing 
should not be included in the File Table. Every data set 
referenced in the File Table must, of course, have a cor- 
responding DD card in the execute deck. 


The File Table is constructed by coding GENFTBLE macros, See 
Appendix D. One GENFTBLE macro must be coded for each file 
to be included in the table. The macros are contained ina 
CSECT named PMIFILET. Following the last GENFTBLE macro, a 
PMISTOP macro must be coded. The general structure of the 
File Table is: 


PMIFILET CSECT 
ENTRY PMIFILTB 
PMIFILTB EQU . 
GENFTBLE .. . 
GENFTBLE .. . 
PMISTOP 
END 
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The complete File Table, then would look as follows: 


PMIFILET CSECT 


ENTRY PMIFILTB 
PMIFILTB EQU * 

GENFTBLE FNAME=DES@9f ,BLKSIZE=759, TYPE=BDAM 

GENFTBLE FNAME=RCT£OP ,BLKSIZE=1999,TYPE=BDAM 

GENFTBLE FNAME=VRB£PP ,BLKSIZE=759,TYPE=BDAM 

GENFTBLE FNAME=USERFILT,BLKSIZE=xxxx,TYPE=ISAM, 


DESNUM=7 
* BLKSIZE FOR DES#G9,RCTGGP,VRBYLZP CORRESPONDS TO INTERCOMM 
* RELEASE SPECIFICATIONS. USER MUST CHANGE FOR LARGER TABLE 


* ENTRIES. INSERT ADDITIONAL ENTRIES FOR USER FILES HERE.. 
* 


PMISTOP 
END 


For a user file, TYPE= may be either BDAM:or ISAM. FNAME=, 
of course, is the ddname of the user file. The DESNUM= para- 
meter contains the record number of the FDR for this user 
file. 


Format Description Records 


Each file to be accessed by the CHANGE/DISPLAY utility must 

be described by a Format Description Record. Each format of 
intersubsystem message to be processed for OUTPUT must also 

be described by an FDR. Format Description Records are as- 
sembled and then loaded on to the Format Description File 
(DES9#6). Retrieval of an FDR from this file is based on 

the record number supplied in the File Table or Change Table. 
The FDR defines exactly how CHANGE/DISPLAY is to edit and pro- 
cess each field in a record. 


The individual FDR consists of a header portion followed by 
detail segments. The header portion supplies information rele- 
vant to all records on the file. Each detail segment de- 
scribes a particular data field within a record. The header 
portion is generated by an FDHDR macro instruction; detail 
segments are generated by FDETL macros. (These macro instruc- 
tions are described in detail in Appendix D; examples of their 
use are included below.) 


CHANGE/DISPLAY allows one group of repetitive fields to be 
included at the end of a record being processed. When CHNG 
transactions are entered for repetitive fields, each field 
must be identified by a secondary key. The entire length of 
the repetitive portion is indicated in the FDR header 
portion; each field in the repetitive group is defined by 
one FDETL macro. That item which is the secondary key must 
be so flagged in the detail segment of the FDR. (On CHNG 
transactions, the information entered with the SKY Parameter 
will be used to search the repetitive portion of the record.) 
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A record format as follows would be described by one FDHDR™ 
Macro and seven FDETL Macros. 


secondary secondary 
key|data|/data|data ke rdatal] rdata2 kK @ rdata 
header portion repetitive portion 
secondary 
rdata2);  §_— | key rdatal|rdata2|FFFFF..... FF 


Certain fields may require editing other than simple conversion 
to character format for transmission to the terminal. Describ- 
ing editing for DISPLAY is accomplished by specifications in 
the FDETL macro; for example: 


A field has been defined by the following FDETL macro: 


FDETL NAME=FLD@1,OFSET=$,FRMAT=PACK,LEN=8 ,CODE=1, 
PADD=LEFT,PDCHR=BLANK,EDIT=NUM 


Actual data on the file is: 
Cc 2H 6G 64 56 78 91 23 OF 
Output at the terminal would be formatted as follows: 
346 bbbB4 ,567,891,236 (pad with blanks on left) 


If padding had not been specified, data at the terminal 
would appear as follows: 


4,567,891,23646B6646bKB (default pad with blanks on right) 
Note that in either case the displayed length is 19 bytes. 


If editing is requested on a character field, the field must 
be the maximum length as defined, not padded with blanks. 
Blank padding will lead to invalid data for packing. The 
edited length of data items must be considered in the OFT 
positioning specifications. The following table shows the 
edited length of data items after processing by CHANGE/ 
DISPLAY. To use the table: 


Ls Look at the FRMAT column for the type of data on the 
file. 
2. Look at the row in that column with the length of the 
| field to be displayed 
« 3. Scan across to the correct EDIT column to find the 
displayed length of the field. 


fe, 
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Change Table 


The Change Table associates identifiers of fixed format mes- 
Sages for OUTPUT with Format Description Records. It must 
be built as a separated CSECT named CHNGTB. Entries are two 
lines each, the first line is a DC of CL8 containing the 
format identifier. The second line is a DC containing the 
RBN of the FDR to be accessed. The following sample shows a 
table containing 3 entries. 


CHNGTB CSECT 
DC CL8'MSGDSPL' 
DC A(6) 
DC CL8'MSGDSP2'! 
DC A(1l) 
DC CL8'REPORTC' 
DC A(2) 
PMISTOP 
END 
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Cc The message identified by the name MSGDSPL will be processed 
using the FDR at RBN 6 on the DES#@@@G file. The message 
MSGDSP2 will be formatted for OUTPUT in accordance with the 
FDR at RBN 1. Message REPORTC will be processed using FDR 
at RBN 2. 


Key Table 


The Key Table consists of entries associating particular key 
conversion routine numbers with specific addresses, The CSECT 
name must be KEYTABLE. The following example shows a table with 
a Single entry for key routine ll. Entry point for this routine 
is named KEYRT1ll. The File Description Record specifies the 

key conversion routine for each file. 


KEY TABLE CSECT 
DC A(11),V(KEYRT11) 


PMISTOP 
END 


Coding Key Conversion Routines is discussed ina later sec- 
tion. 


Pattern Table 


The Pattern Table is resident in a CSECT named PTRNTBLE. It 

| is created by coding a series of PATRN macros. (See Appendix D). 
For using EDIT= parameter coded in an FDETL macro (Format 
Description Record detail segment), there must be a correspond- 
ing entry in the Pattern Table. Following is an example of a 
Pattern Table: 


PTRNTBLE CSECT 
PATRN NUMBER=DATE,PATTRN=DATE ,MAXSIZE=8 
PATRN NUMBER=DOLLAR, PATTRN=DOLLAR 
FLOAT=$ ,MAXSIZE=42 
PATRN NUMBER=NUMERIC,PATTRN=NUMERIC 
MAXSIZE=41 
* 


* USER SUPPLIED PATTERNS GO HERE 
* 

PMISTOP 

END 


Any packed or binary fields which the user wishes to convert to 
. character format require a user pattern table entry unless 
( covered by the PATRN macros in the supplied PTRNTBLE CSECT. 
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Sample Table Entries 

The examples in this section are included to assist the user ~ 
in understanding the Table entries specifying record format 
descriptions. 

The examples illustrate: 

‘ ISAM File Record, no repetitive group (Figure 21) 

, BDAM Filé Record, no repetitive group (Figure 22) 

, ISAM File Record, repetitive group (Figure 23) 


, Intersubsystem Fixed Format message (Figure 24) 


Each example illustrates the record format and associated 
FDR. 
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There exists an indexed sequential file with a ddname ISFILE. 
The key to each record in the file is eight characters. The 
record consists of keys to other ISAM records in the file. 


Each record is 24 bytes long and consists of 3 record keys. 
The second key is the key to this record. The format, then, 
is as follows: 


key 1 key 2 key 3 
718 1516 23 


An Output Format Table entry with number 51 will be built to 
display this record. Item codes in this table for the three 
keys will be 1, 2, and 3. The FDR would be coded as fol- 
lows: 


FDHDR NAME=ISFILE,FIELDS=3,RPTNO=51 

FDETL NAME=KEY$1,OFSET=9,F RMAT=CHAR,LEN=8 ,CODE=1, 
PADD=LEFT, PDCHR=BLANK 

FDETL NAME=KEY@2,OFSET=8 ,FRMAT=CHAR,LEN=8 ,CODE=2, 
PADD=LEFT, PDCHR=BLANK,KEY=YES 

FDETL NAME=KEY6@3 ,OFSET=16,FRMAT=CHAR, LEN=8 ,CODES=3, 
PADD=LEFT,PDCHR=BLANK. 


Figure 21. ISAM File Record, no repetitive group. 
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There exists a BDAM file with a ddname BDFILE. The file 
contains sales information for each product the company 
manufactures. The record contains: 


Product Current Week Previous Week 


Name Sales Sales 


Current Month Previous Mont 
Sales Sales 


Assuming that an Output Format Table with report number 
52 is to be built, the FDR would be coded as follows: 


FDHDR NAME=BDFILE,FIELDS=7,RPTNO=52,KEYRT=2 

FDETL NAME=PRODT,OFSET=9,FRMAT=CHAR,LEN=16, 
CODE=1,PADD=LEFT,PDCHR=BLANK 

FDETL NAME=CUWIC,OFSET=16,FRMAT=PACK,LEN=19, 
CODE=2,PADD=LEFT,PDCHR=BLANK 

FDETL NAME=PVWKS,OFSET=26,FRMAT=PACK,LEN=128, 
CODE=3 ,PADD=LEFT,PDCHR#*BLANK 

FDETL NAME=PERWK, OFSET=36,F RMAT=PACK,LEN=5, 
CODE=4,PADD=LEFT, PDCHR=BLANK 

FDETL NAME=CUMOS,OFSET=41,FRMAT=PACK,LEN=18, 
CODE=5, PADD=LEFT , PDCHR=BLANK 

FDETL NAME=PVMOS ,OFSET=51,FRMAT=PACK,LEN=128, 
CODE=6,PADD=LEFT,PDCHR=BLANK 

FDETL NAME=PERMO,OFSET=61,FRMAT=PACK,LEN=5, 
CODE=7 , PADD=LEFT, PDCHR=BLANK 


Figure 22. BDAM File Record, no repetitive group. 
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There exists an ISAM file by the name of MASTER. Records 
contain a key (city) followed by a repetitive group consist- 
ing of: 


Customer ID (secondary key) 
Credit 
Debit 


The repetitive group repeats up to 19@ times. The record, 
then, looks as follows: 


Assuming the output report number for this record is 53 and 
that a user key routine number 11 is required, the FDR 
would be coded as follows: 


FDHDR NAME=MASTER,FIELDS=4,RPTNO=53,KEYRT=11, 
REPSZ=29 

FDETL NAME=CITY,OFSET=§,F RMAT=CHAR, LEN=19,CODE=1, 
KEY=YES 

FDETL NAME=CUST,OFSET=1%8,FRMAT=BIN,LEN=4 ,CODE=2, 
FLD=REPET ,PADD=LEFT , PDCHR=ZERO,EDIT=NUM, 
SUBKY=YES 
NAME=CREDT,OFSET=14,FRMAT=PACK,LEN=8,CODE=3, 
FLD=REPET,PADD=LEFT,PDCHR=BLANK,EDIT=DOLL 
NAME=DEBIT,OFSET=22,FRMAT=PACK, LEN=8 ,CODE=4 
FLD=REPET, PADD=LEFT,PDCHR=BLANK,EDIT=DOLL 


Figure 23. ISAM File Record, repetitive group. 


81 


IPN: 042 4/1/74 


Fixed Format Message: 


Message Header: 


nnnn X'OO' C'H' — _ C..6) IEG -<C ata eee ee 


MSGHLEN MSGHRSC MSGHTID MSGHVMI 


Message Text: 


|} Aaaaaaaa {ijnnn | data fields in fixed format 


lL sseeeuies output format number 


segmented message indicators 
format identifier 


Format Description Record: 


FDHDR NAME=aaaaaaaa,FIELDS=x,RPTNO=xx 
FDETL 
FDETL 
description of message text fields 
(no FDETL macros for the 12-byte prefix) 


* The segmented message indicator is used to place the 
appropriate value in the VMI field of the message header 
to be routed to the OUTPUT Utility. The correspondence is: 


Segmented OUTPUT 
Message Identifier Message Type ‘Message VMI 
(character) Value 
i) Full Message X'5H * 
1 Header Segment > Gain oe te | 
2 Detail Segment with x52" | 
Repetitive Data 
3 Final Segment x5 37 
4 Detail-Segment with X'5C! 


no Repetitive data 


Figure 24, Intersubsystem Fixed Format Message 
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USER EXITS FROM CHANGE/DISPLAY 


The CHANGE/DISPLAY module provides two user exits. Through 
these, the user has the following options: 


i To perform special editing on a key supplied via a 
CHNG or DSPL verb with a key conversion routine. 
24 To examine and further alter a record about to be re- 


written during processing of a CHNG transaction. 
Coding Key Conversion Routines 


Normal processing of keys by CHANGE/DISPLAY is based on the 
FDR for ISAM keys. BDAM RBN's are simply converted to binary. 
(Note that for normal processing of ISAM Keys, KEYRT= is not 
coded in the FDHDR macro. For normal processing of BDAM 

RBN's the FDHDR macro should specify KEYRT=2.) 


If key processing other than that just described is desired, 
the user must code his own routine. The numbers assigned to 
these routines must be 5 or greater. This number is coded in 
the KEYRT= parameter of the FDHDR macro; and the key routine 
itself is identified by the Key Table entry described above. 


The CHANGE/DISPLAY subsystem will pass a five word parameter 
list to the user-written routine: 


1. Address of the key to be manipulated. The first 
byte is the length of the key in binary, followed 
by the key as entered at the terminal. 

2. Address of SPALIST. 

3. Address where manipulated key value is to be 
placed when routine is finished. Maximum: length 
of manipulated key is 255. 

4. Address of Format Description Record for this 
file. ; 

5. Address of File Table Entry for this file. 


The user must also supply a return code in register (15) to 
indicate whether processing was successful or not. Return 
codes are: 


@ - Successful key processing 


1 - Unsuccessful, no CHANGE/DISPLAY action is taken. 
Instead, an error message is passed to the’ terminal. 


CHANGE User Exit (CHNGEXIT) 
The CHANGE User exit allows the user to modify a CHANGEG 
record before the file has been updated. The user must code 


the routine to effect this, and, it must have a CSECT name or 
entry point name of CHNGEXIT. CHANGE will CALL CHNGEXIT if 
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such a module is linkedited with INTERCOMM. The parameter 
list passed to CHNGEXIT consists of three words: 


1. Address of edited input message. 
2. Address of System Parameter List. 
3. Address of record that was changed. 


When control returns to the CHANGE subsystem, the record is 
updated. 


CHANGE/DISPLAY ERROR MESSAGES 


Error messages reflecting problems encountered during CHANGE/ 
DISPLAY processing are generated and queued for processing via 
the OUTPUT Utility. The messages are formatted according to 
OFT entries. Each message contains the input message FLM data 
(ddname) or fixed format name and other identifying information 
to be returned to the originating terminal. 


Each error message explicitly defines the reason for rejecting 
the CHANGE/DISPLAY transaction, for example: 


"NO FDR FOUND FOR FILE (ddname)" 
"KEY WAS NOT DEFINED IN FDR FOR (ddname)" 


“CHANGE TABLE NOT FOUND OR NO ENTRY IN 
CHANGE TABLE FOR (format name)" 


"A RECORD DOES NOT EXIST WITH THE KEY 
ON FILE (ddname)." 


For a precise listing of CHANGE/DISPLAY Utility error messages, 


the OFT entries on the INTERCOMM Release Library should be 
assembled (or printed) by the INTERCOMM System Manager. 
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DISK RESIDENT TABLE ENTRIES FOR THE UTILITIES 


GENERAL CONSIDERATIONS 


Table entries for EDIT and OUTPUT are optionally disk resident; 
Format Description Records for CHANGE/DISPLAY are always disk 
resident. The System Manager(s) for each INTERCOMM installa- 
tion should maintain and control assignment of table entries 

to disk. Individual table entries on disk are maintained by 
the user on symbolic and load module libraries (partitioned 
data sets) and loaded to a BDAM dataset for retrieval at 
execution time. An INTERCOMM batch utility is used to ac- 
complish the file load process. 


Each INTERCOMM Utility uses a separate BDAM dataset for its 
table entries as follows: 


, EDIT (ddname=VRBG@G9Z): Each record represents one EDIT 
Control Table (ECT) entry giving specifications for EDIT- 
ing one verb. 


‘ OUTPUT (ddname=RCT#@@9): Each record represents one 
OUTPUT Format Table (OFT) entry giving specifications 
for formatting one message. INTERCOMM error messages 
generated via OFT entries are disk-resident. 


: CHANGE/DISPLAY (ddname=DES#9%): Each record represents 
one Format Description Record (FDR) giving record fiormats 
for data files accessed through CHNG/DSPL verbs or 
record formats for fixed format messages from an 
application subsystem to be converted to variable 
character text and passed to the OUTPUT utility. 


All table entries on disk are fixed length records. 


Each disk resident table is described in the CHANGE/DISPLAY 
File Table (PMIFILET CSECT). Initial table entries for VRBSOZ, 
RCT00B, DESPHG are provided on the installed INTERCOMM librar- 
ies. The maximum blocksize specified by these entries is 750 
bytes. Care must be taken to ensure this table is modified 

if and when an installation's own disk resident table entries 
are longer than this specified value. 


Each of the previous sections of this document have described 
coding conventions for the individual table entries for each 
utility. Figure 25 summarizes coding conventions, naming and 
dataset conventions (detailed later in this section) for each 
Utility. 
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CHANGE/ 


OUTPUT DISPLAY ) 


Esai eC ae) RE ne ea ak) Fa eRe es SEE 
ddname of disk VRBGDD RCTS PP DES SPH 
resident table 
entries in INTER- 

COMM execution JCL 

PMIFILET blocksize|75g 1446 75@ 
specification at 

installation time 

Symbolic Table PMI.SYMVRB PMI.SYMRCT PMI.SYMDES 
Entry Library 

(created at in- 

stallation time) 
Load Module Table PMI .MODVRB PMI.MODRCT PMI .MODDES 


Table Entry 
Library member 
name convention 


Entry Library 
— 


(created at in- 
stallation time) 

VERB macro, REPORT 
RBN=nnnnn macro, 


NUM=nnnnn 


Coding convention 
within disk resi- 
dent entry 


VERBTBL PMIRCNTB PMIFILET 
CSECT: CSECTs CSECT: 
Core-resident VERBGEN None GENFTBLE 
table require- macro plus (OFT#-1 is macro, 
ments. in-line assem- | used for DESNUM=DES@@8rbn 
bly of disk RCT#OOrbn) or 


CHNGTB CSECT: 
DC A(DES#OGrbn) 


resident 
entries 


Figure 25. Summary Requirements for Disk-Resident Table 
Entries. 
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The File Load Program 


The File Load Program is a generalized batch utility supplied 
with INTERCOMM which transfers members of a Partitioned Data 
set to relative blocks in a BDAM data set. Given that member 
naming conventions are followed, it can be used to convert any 
PDS to BDAM. 


The File Load Program is linkedited and used at INTERCOMM 
installation time to initially load all error messages gene- 
rated via OUTPUT Utility OFT entries to disk. The following 
JCL may be used to linkedit: 


Lf EXEC LKEDP,Q=LIB,LMOD=PMIEXLD 
//LKED.SYSIN DD‘ * 

INCLUDE SYSLIB (BATCHPAK) 

INCLUDE SYSLIB(PMIDCB) 

INCLUDE SYSLIB(PMIFILET) 

INCLUDE SYSLIB(PMISERC2) 

INCLUDE SYSLIB(IXFABEND) (not required for VI.1) 

INCLUDE SYSLIB(IJKDSP@1) 

INCLUDE SYSLIB(IXFHND@H) 

INCLUDE SYSLIB(IXFHND#1) 

INCLUDE SYSLIB (PMILOAD) 

ENTRY PMILOAD 

NAME PMIEXLD (R) 


At file load execution time, a SYSIN control card specifies 

VRB, RCT, or DES or a user-assigned file identifier to define 
program logic, represented by XXX in the following naming 
conventions. A partitioned data set specified by: ddname 
XXXLOAD is searched for member names XXXnnnnn. Members are 
loaded sequentially to the BDAM data set specified by a ddname 
XXX@O@ with the RBN being one less than nnnnn. Members are 
loaded until a member on the PDS is “not found". Hence, 

member names must ascend sequentially from XXX#99@1 to XXXnnnnn, 
incremented by 1 for each new member added to the PDS. 


With INTERCOMM VI.1 and subsequent versions, the File Load 
Program has been modified allowing the SYSIN data set to specify 
replacement of one existing BDAM data set table entry or creation 
of the BDAM data set from a given range of PDS member names re- 
gardless of the existence of member names in ascending sequential 
order or not. See "INTERCOMM VI.1 Enhancements” at the end of 
this chapter. 


The actual JCL for loading the disk-resident table for each 
of the Utilities is detailed below. Each Utility's table 
entries may be loaded as a separate job step, or the JCL may 
be combined to load all three data gets (VRBAMA, RCTPAOA, and 
DES#J¢G@B) in one step. 
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Loading ECT Entries to Disk 


1. Create a symbolic library (PMI.SYMVRB) and a load 
module library (PMI.MODVRB) for the EDIT Control 
Table (ECT) entries on disk. These libraries are 
normally allocated and catalogued at INTERCOMM 
installation time. 

2. Add the appropriate ECT to the symbolic library (PMI. 
SYMVRB). On the ADD card, code NAME=VRBXXXXX where 
XXXX¥X corresponds to the RBN operand of the VERB 
macro for this particular entry. Disk resident 
entries must be named VRB#GHG1 to VRBnnnnn, numbered 
sequentially. The following JCL might be used: 


// EXEC LIBE,Q=VRB 
./ ADD NAME=VRBSGSG1 
*ECT ENTRY TO BE LOADED TO DISK 


VERB - - -,RBN=$1 


PARM 


PARM 
/* 


Note the absence of CSECT, PMISTOP, and END cards. 
These members might also be COPYed during the assembly 
of the core-resident ECT. The symbolic form of the 
table entry is now VRBS4GG1 on PMI.SYMVRB. 

3. Assemble and link-edit the ECT into the load module 
library (PMI.MODVRB). The following JCL might be 
used; 


// EXEC ASMPCL,Q=VRB, LMOD=VRBO00O1, NAME=VRBOPOO1 


Ignore the assembly errors for lack of CSECT and END 
card. The load module form of the table entry is now 
member VRB#PZHG1l on PMI.MODVRB. 

4. Load all disk-resident ECT's (VRB#9981 to ¥VRBnnnnn) 
to the EDIT Control File, ddname=VRBGGZH. The follow- 
ing JCL might be used: 


// PGM=PMIEXLD,PARM='NOCHECK' 
//STEPLIB DSN=PMI,MODLIB,DISP=SHR 

//VRBDBB DSN=VRB#GH,DISP=(NEW,KEEP), 

// SPACE=( ), 

// DCB=(DSORG=PS,BLKSIZE=nnn,RECFM=F), 
// UNIT=SYSDA,VOL=SER=nnnnnn 


//VRBLOAD DSN=PMI.MODVRB ,DISP=SHR 
//SYSPRINT SYSOUT=A 

//SYSIN * 

VRBSDD 

/* 
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The members from the partitioned dataset VRBLOAD are 
now blocks on the BDAM dataset VRB@G@BZ, The actual 
RBN is one less than tne number XXXXX described 
above. 


Loading OFT Entries to Disk 


To create the Output Format Table, the following procedures 
must be followed: 


de 


// 


/* 


Create a symbolic library (PMI.SYMRCT) and a load 
module library (PMI.MODRCT) for the Output Format Table 
(OFT) entries on disk. These libraries are normally 
allocated and catalogued at INTERCOMM installation 
time. 

Add the appropriate OFT to the symbolic library 
(PMI.SYMRCT). On the ADD card, code NAME=RPTXXXXxX 
where XXXXX corresponds to OFT number for this particu- 
lar entry. INTERCOMM error messages generated from 
disk resident OFT entries are contained on PMI.SYMREL 
and PMI.MODREL with member names RPT#PGHG1l to RPTGPOG5G. 
User OFT entries to be loaded to disk must be named 
RPT@G9G51 and up, numbered sequentially. The follow- 
ing JCL could be used: 


// EXEC LIBE,Q=RCT 
//LIB.SYSIN DD * 
./ ADD NAME=RPT#POG51 
* OFT NUMBER 51- DISK RESIDENT 


REPORT NUM=51 


Note the absence of CSECT, PMISTOP, and END cards. 
The symbolic form of the table entry is now RPT§GZG51 
on PMI.SYMRCT. 

Assemble and linkedit the OFT into the load module 
library (PMI.MODRCT). The following JCL might be 
used: 


EXEC ASMPCL,Q=RCT,NAME=RPT#$$51,LMOD=RPT$GG51 


Ignore the assembly errors for lack of CSECT and END 
cards. The load module form of the table entry is now 
member RPT##G@G51 on PMI.MODRCT. 


89 


SPR 174 6/80 


4. Load all disk-resident OFT's (RPTOOO0O1 to RPTnnnnn) to the 2 
Output Format File, ddname-RCTO00. The following JCL might 
be used: 


// PGM=PMIEXLD , PARM='NOCHECK' 

//STEPLIB DSN=PMI,MODLIB,DISP=SHR 

/ /RCTOOO DSN=RCTO000 , DI SP=(NEW, KEEP ) , SPACE=( ys 
// DCB=(DSORG=PS , BLKSIZE=nnn, RECFM=F) , 

// UNIT=SYSDA, VOL=SER=nnnnnn 


//RCTLOAD DSN=PMI.MODRCT,DISP=SHR 
// DSN=PMI .MODREL , DISP=SHR 
//SYSPRINT SYSOUT=A 

//SYSIN * 

RCTOOO 

/* 


The members from the partitioned data set RCTLOAD are now 
blocks in the BDAM dataset RCTOOO. The actual RBN that the 
OFT entry will occupy is one less than the number XXXXX 
(defined above). 


NOTE: To change the Output Format Table block size from the 
Intercomm release, the following steps should be taken: | ; 


1. The File Table (PMIFILET CSECT) entry created via 
the GENFILE macro for RCTOOO must be changed from 
BLKSIZE-1000 to BLKSIZE=nnnn, where nnnn is the new 
block size. PMIFILET must be reassembled. 


2. The File Load program (PMIEXLD) must be relinkedited 
to contain the new block size. 


3. Execute the File Load program (PMIEXLD) in RCTOOO 
with the JCL shown above. 


Loading FDR Entries to Disk 


To create the Format Description File, the following procedures 
must be followed: 


1. Create a symbolic library (PMI.SYMDES) and a load module 
library (PMI.MODDES) for the Format Description Records. 
These libraries are normally allocated and catalogued at 
Intercomm installation time. 


2. Add the $$ appropriate FDR to the - symbolic’ library 
(PMI.SYMDES). On the ADD card, code NAME=DESxxxxx where 2 
Xxxxx is one greater than the resulting RBN after the file 
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load program is executed. The user must relate’ the 
corresponding ddname and FDR by the DESNUM parameter of the 
GENFTABLE macro for user files, or relate the fixed format 
identifier and FDR by the number indicated in the CHANGE 
table for fixed format message text descriptions. The first 
record should be DESOOO0O0O1; the second, DESO0002; etc. No 
number should be skipped. The following JCL can be used: 


// EXEC LIBE,Q=DES 
//LIB.SYSIN DD % 
./ ADD NAME=DESO0001 
* FORMAT DESCRIPTION RECORD 1 
DESOOOO1 CSECT 


FDHDR 
FDETL 
FDETL 
END 
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The symbolic form of the table entry is now member 
DES@ZGGZl on the library PMI.SYMDES. 


Assemble and link-edit the FDR into the load module 
library (PMI.MODDES). 


The following JCL might be used: 


ASMPCL,NAME=DES#@9991,LMOD=DESPHPH1, 


Q=DES 


The load module form of the table entry is now member 
DES@G@ZG1l on the library PMI.MODDES. 


Load all FDR's (DES#@9G1l to DESnnnnn) to the Format 
Description File, ddname=DES@#@. 


The following JCL might be used: 


// EXEC PGM=PMIEXLD,PARM='NOCHECK' 

//STEPLIB DD DSNAME=PMI.MODLIB,DISP=SHR 

/ / DESY BS DD DSNAME=PMI.DES#9ZG, 
DISP=(;,KEEP) ,SPACE=(TRK, (1,1)),; 
UNIT=XXXX, VOL=SER=XXXXXX, 
DCB=(DSORG=PS , BLKSIZE=X%¥XXX, 


RECFM=F) 
// DESLOAD DSN=PMI.MODDES, DISP=OLD 
//SYSPRINT SYSOUT=A 
//SYSIN * 
DES PPP 
/* 


The members from the partitioned dataset DESLOAD are 
now blocks on the BDAM dataset DES#@9. The actual RBN 
that the FDR will occupy is one LESS than the number 
XXXXX (defined above). 
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INTERCOMM VI.1 Enhancements 


With INTERCOMM VI.1 (April, 1974) and subsequent versions, 

the File Load Program has been modified allowing the SYSIN 
data set to specify replacement of a specific member of the 
partitioned data set or loading all members within a specified 
range of member names. 


Example 1: To copy PDS member name XXX00007 to the exist- 
ing BDAM data set XXX$@G; the SYSIN data set specifies: 


//SYSIN DD * 
XXX00007 


Example 2: to create the BDAM data set XXX99@ from PDS 
member names XXXOO00OO1 to XXXfnnnn irrespective of the 
number of actual members on the PDS. The SYSIN data set 
specifies: 


//SYSIN Db * 
X¥X¥X000-nnnn 


The File Load Program will copy PDS members in ascending 
sequence to the BDAM data set XXX#$9G beginning with xXxXxX00001. 
When a "member not found" condition arises, the file load 
does not terminate (aS was previously the case) but the last 
member found will be copied to the BDAM data set until the 
next "member found" occurs, or the “upper limit" member 
XXXOnnnn is encountered. To illustrate, assume members 
RPTOOOO1 to RPTOO0050, RPTOO1OO to RPTOO0106 exist on the 
library PMI.MODRCT. Specification to the File Load Program 
as follows; 


//S$83N DD * 
RCT#$P-0110 


will cause creation of a BDAM data set {RCTAPA) with 110 
RBN's. The member RPTO00050 will be duplicated in RBN's 49 
to 98 (once as the actual table entry RBN 49, repeated until 
RPTOO1OO is found and loaded to RBN 99). The member RPTOO0106 
will be duplicated in RBN's 105 to 109. 


There is no limit to the number of control cards input via the 


SYSIN data set. Further, given the proper JCL as discussed earlier, 
several BDAM data sets may be updated or recreated in one execution 


of the File Load Program. 
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TERMINAL DEPENDENT CONSIDERATIONS 


This section provides information pertaining to special con- 
Siderations for terminals with non-standard operating charac- 
teristics. Some of the data covered in this section is as 
follows: 


; Special operating features such as function keys, and 
field formatting 


: Restrictions which may be peculiar to a specific termi- 
nal. 


It is assumed the reader has knowledge of the actual hardware 
operating specifications of each terminal type as described 
by the manufacturer's publications. 


This section may also reference required specifications for 


Front-End Tables as appropriate (also documented in the 
INTERCOMM Operating Reference Manual). 
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THE IBM 3270 


All IBM 3270 Display System components are supported by the 
INTERCOMM BTAM Front-End including the following: 


IBM 3271 control unit, models 1 and 2 
IBM 3272 control unit, models 1 and 2 
IBM 3275 display station, models 1 and 2 
IBM 3277 display station, models 1 and 2 
IBM 3284 printer, models 1 and 2 
Selector pen 

Operator identification card reader 


Both the IBM 3270 Remote and the IBM 3270 local display sys- 
tems are supported by the INTERCOMM BTAM Front-End. Other 
IBM BISYNC devices are also supported on the same line as 
the IBM 3270 display system. The question of whether or not 
the 3270 display system is local or remote is transparent to 
the application program. 


INPUT Message Formats 


The format of the input to the application (or the EDIT 
Utility) depends on whether or not the user intends to use 
the aid or the cursor address. If the user desires neither, 
he should either code HDR3270=NO or omit this parameter from 
the BTVERB macro used to define his verb in the Front-End 
Verb Table (BTVRBTB). The following is an example of an 
input transaction without a 3270 header. 


INTERCOMM HDR|VERB [] DATA 


If the user desires either the aid or the cursor address, he 
must code HDR3270=YES in his verb definition (BTVERB macro) 
in the BTVERBTB. The following is an example of an input 
message with the aid and the cursor address header (3270 
header) : 


| INTERCOMM HDR ca ArDx AcuRYYADATA..., | 
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where 


X=the aid byte; YY=the cursor position bytes. If the 

3270 header is desired and the aid is that of an input 
that does not contain a cursor address, a dummy cursor 
address of "home" will be provided. 


The format of DATA depends on whether or not the terminal is 
operating with "formatted" screen capabilities as shown in 
figure 26 and 27. 


Bypassing the Edit Utility 


If the application programmer desires, the input message may 
be processed without the use of the EDIT Utility. Under this 
method, either formatted or unformatted input is acceptable; 
however, all editing must be done by the application program. 
If the input screen is unformatted then VERB and DATA is what 
was entered on the screen. If the input screen is formatted 
VERB is the contents of the first "modified" field on the 
screen prefixed by their SBA sequences. In either case, the 
verb may be "locked", or part (or all) of the transaction 

may have come from the table used for program attention keys. 


Using the EDIT Utility - Unformatted Input 


If the input screen is unformatted and the aid and cursor 
position are not désired, the input to the EDIT Utility can 
be of any standard form currently accepted by the EDIT 
Utility (positional or keyword). If it is desired to use the 
3270 in this mode, no additional facilities of edit are 
needed, no existing application programs or tables need be 
changed. The output of the EDIT Utility will be either 
standard form desired (fixed, variable). 


If the input screen is unformatted and the aid or the cursor 
position is desired, the EDIT Control Table VERB definition 
must be modified to accept this additional data as para- 
meters of the verb. If the input is keyword, an AID parm of 
l1 byte and a CUR parm of 2 bytes must be defined anywhere 

in the verb definition. 


VERB1 VERB VERB ,@1,156,5,FIX=YES,KEY=YES 
PARM CUS ,61,0,25,8PGPGBG11 
PARM ADR, £$2,0,26, 00 PPPG11 
PARM C/S,63,8,25,PHPGPG11 
PARM AID,94,8,1,1696@111 
PARM CUR,@5,6,2,1668@111 
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| [VERB *DATA1 *DATA2 
| 


Unformatted screen 
(e.g., positional) 


Message Input - No Aid or cursor address: 


INTERCOMM HDR | VERB*DATA1*DATA2 


With aid and cursor address: 


EB 
INTERCOMM HDR | VERB*AIDX CURYY DATAI1*DATA2 
L L X 


Figure 26. 3270 Input Message Format - Unformatted Screen 


Message Input - 


(]V=RBL] NAME[(] xxx VERB,XXX,YYY fields have modified 


data tags on 


Formatted screen 


Message Input - No aid or cursor address: 


EI 
INTERCOMM HDR } VERB* | SBA seq XXX | SBA seq YYY 
| x 


Message Input - With aid and cursor address: 


INTERCOMM HDR | VERB*/ AIDX | N | CURYY |N | SBA seq XXX SBA seq YYY 


L L 


Figure 27. 3270 Input Message Format - Formatted Screen 


95 


parm of 5 bytes must be defined as the first 2 parms of that 
verb. (If LINE=YES is specified PMIELIN macros must be 
coded): 


If the input is positional, an AID parm of 4 bytes and a CUR ) 


VERB, (@2,256,5,FIX=YES , KEY=NO 
AID,$4,8,4,19@99111 
CUR, G5,8,5,19999111 


CUS ,91,%,25, 09909119 
ADR, 92,989,208, 98992119 
C/S,93,8,25,8P9GG119 


For positional input the letters AID and CUR will be passed 

to the application as data along with the actual aid and 

cursor position. (A special Edit Routine may be written to 
strip this off.) If either PARM is coded with a length of zero, 
that parameter will be omitted from the output of the EDIT 
Utility. 


Using the EDIT Utility - Formatted Input 


A facility has been added to the EDIT Utility to allow the pro- 

cessing of 3270 formatted input. With this facility, the screen 

data will be treated as positional data. Instead of a separator 
indicating the position of the field, a buffer address is used. 

It is required that the user code the buffer position of each > 
field as the CHAR-ID of that field in the PARM macro when defin- 

ing that verb in the EDIT Control Table. (For standard position- 

al input, the CHAR-ID is used only for error reporting identifi- 

cation.) 


If the AID or CURSOR address is desired, an AID parm of 4 bytes 
and a CUR parm of 5 bytes must be coded as the first 2 parms of 
that verb. The output from the EDIT utility will be either of 
the standard formats (i.e., fixed, variable). 


Figure 28 shows a formatted screen appearing at the terminal al- 
lowing the operator to enter customer name, salary, title, and 
phone #, an input message processed by EDIT, the ECT, and EDIT 
results. 


Alternatively, the user may code PREONLY=YES in the Edit Control 
Table VERB macro. In this case the SBA sequence in the incoming 
message will be replaced by the system separator character. The 
individual data fields will not be edited. This technique effects 
conversion of a 3270 formatted input message to standard posi- 
tional input as if the message forwarded to the subsystem had 

come from an IBM 2260-type terminal. 
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EDIT example - Formatted Screen (Sheet l of 2) 


Figure 28. 
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INPUT TO EDIT UTILITY 


N N 


Screen position* 


S 
5 hors JOHN B DOE 012525 
A 


Po WwW 


IN BTVERB 
HDR3270=YES 


*All SBA addresses really are in buffer address form 


EDIT Control Table Entry: 


VERB 


VERB 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 


VERB,0O1,256,6, FIX=YES, KEY=NO, LINE=NO 
AID,05,0,4,10000111 
CUR,06,0,5,10000111 
40F5,01,0,22,10000111 
C15F,02,0,6,10000111 
C24A,03,0,11,10000111 
C2F0,04,0,12,10000111 


RESULT OF EDIT PROCESSING (Input to Application Program) : 


MSG HEADER 
Ol 


Figure 28. 
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EDIT example 


Formatted Screen (Sheet 2 of 2) 
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"ATTENTION" Selector Pen Input 


If the input is generated by an operator touching a selector 
pen "ATTENTION" field, the input buffer will consist of SBA 
sequences only, no data will be sent in from any "modified" 
fields read. Therefore, the user is advised not to define 
data entry fields in any format screen that contains an 
"attention field". (Data entry fields may be defined with 
"selection" fields and "selection" fields may be defined with 
"attention" fields.) 


Since no data is received from the screen, a verb will have 
to be appended to the contents of the input buffer. In order 
for the verb to be appended, either the terminal should be 
"locked" to a verb or data with a verb should be specified in 
the Front-End table entry defined for this AID. 


For all fields read, the EDIT Utility will generate an "xX" 

as the data read. In other words, an "attention" screen will 
be processed by the EDIT Utility as though each field read 
contained an "X", In the verb definition in the EDIT Control 
Table each field should be defined as a one byte field. agp a 

a field is read, the output from the EDIT Utility will have 
an X as the contents of the field. 


If the EDIT Utility is not used, the appended prefix to the 
screen will be followed by only SBA Sequences (from the screen) 
and an ETX. 


Output Message Formats 


All messages going to any 3270 must begin with a valid com- 
Mand (i.e., write: C'l', erase write: C'5', erase all un- 
protected: C'?'), a WCC, and an SBA Sequence. In addition 
all messages going to a remote 3270 must be prefixed by an 
STX and an ESC. 


The INTERCOMM BTAM front-end will prefix all output messages 
for a given device type (see BDEVICE STCHAR=). The remote 
3270 BDEVICE macro must specify STCHAR=0227 (STX,ESC); the 
local 3270 may omit the STCHAR parameter from the BDEVICE 
macro. 


The INTERCOMM back-end message OFT entries and INTERCOMM BTAM 
front-end messages do not contain any command, WCC or SBA 
sequence. A valid command, WCC and SBA sequence must be 
specified for a given device type (see BDEVICE CTCHAR=), For 
all BTAM front-end messages and for all INTERCOMM back-end 
messages that do not contain a valid command, this additional 
information will be taken from the CTCHAR= parameters speci- 
fied on the BDEVICE macro and placed at the beginning of the 
message. 
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BypasSing Formatting by the OUTPUT Utility 


The application program may build the entire output message 
including the command, WCC, SBA sequence and any orders and 
data needed. This message can be sent to OUTPUT using a VMI 
of X'S57'; the OUTPUT Utility will simply forward that mes- 
sage to the front-end. 


All messages written to a 3270 display system must contain a 
prefix containing a command sequence and an SBA sequence. As 
previously noted, the INTERCOMM Front-End will optionally pre- 
fix all output messages going to a specific device type. 

Using this option it is unnecessary to change either the ap- 
plication program or the OUTPUT Format Table. However, all 
messages to the same device type will have the same prefix. 


If the application has OFT entries or messages already opera- 
tional and these messages contain characters acceptable to 

the 3270, no program change or table change is necessary. NL 
characters do not function on a 3270 display. To allow NL 
characters in a 3270 screen an additional facility of the oOUT- 
PUT Utility translates all NL characters to SBA sequences. 


Using the Output Utility - Minimal user modification 


In order to have greater flexibility of type of command and 
SBA sequence, the user may include the prefix in the beginning 
of each output message. In order to utilize Output formatting 
Capabilities for 3270 messages without using the additional 
formatting of the OUTPUT Utility, the application may define 
all control bytes in the message and thus eliminate NL charac- 
ters. 


Using the Output Utility-Extended Facilities for the 3270 


The User may choose to implement the following OUTPUT Utility 
Features to fully utilize the hardware characteristics of the 
3270. 


Generating a Format Screen or Print Buffer: 


In order to facilitate the use of the format generating features 
of the Output Utility, operands have been added to the REPORT 
and ITEM macros. 


The COMM and WCC operands of the ITEM macro may be used to de- 
fine a command and WCC to prefix a specific display. MThese 
keyword operands must be placed in the first ITEM macro coded; 
causing a command and a WCC to be generated in a 254 ITEM. 

(An SBA sequence to address zero will also be generated.) 

Since the command, the WCC and the SBA sequence take up 5 
positions, the first ITEM macro must be coded with an additional 
5 positions in the TO=parameter. 
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The ATT operand of the ITEM macro may be used to define a 
field. If this parameter is used, an SF order and an attrib- 
ute byte will be generated to precede the item defined. If 
the ATT operand is omitted no SF and ATT byte is generated. 
The SF and the attribute take up 2 positions in the buffer 
used to create the report. Therefore, any ITEM macro that 
specifies the ATT= parameter must be coded with an addition- 
al two positions in the TO= parameter. 


In order to fully utilize the features of the IBM 3270; if 
more than 4 contiguous blanks are to be transmitted, or more 
than 4 of the same non-blank characters, the "repeat to 
address" sequence will be generated by the OUTPUT Utility. 

If it is desired to define more than 4 contiguous blanks or 
more than 4 of the same non-blank characters, these positions 
in the OFT should be defined as unique items; a following 
data item starts a new field. Any order that changes the 
current buffer address (SBA,RTA,EVA,TAB) should not be defined 
within data items unless that item is the last item of the 
message and the data begins with an SBA order. 


Any NL orders can be inserted by either the application or 
the OUTPUT Utility. Any Insert Cursor or EM orders should be 
specified in regular data items. Any order that takes up a 
buffer position should be coded as an item code 255 item. 

Any order that does not take up a buffer position should be 
coded as an item code 254 item. If the report is to go to a 
screen (WCC#PRINT) any NL orders will be replaced by an SBA 
sequence by the Output Utility. 


As previously noted, an SBA order to buffer position ZERO 
will be generated by the first ITEM macro. If it is desired 
to have a display start at other than buffer position ZERO, 
specify as many NL characters as needed to position the re- 
port at the desired line location. 


Figure 29 illustrates a sample OFT for Screen Generation, 
resulting display at the 3270; and an input message to OUTPUT 
requesting the OFT screen generating entry, and the actual 
message produced by OUTPUT. 


Filling in a Screen Format: 


In order to facilitate the filling in of unprotected items of 
a screen format (already displayed) by an application program, 
a VMI of X'56' has been added to the Output Utility message 
types. With this facility the application program can pass 
to the Output Utility the report number of the screen format 
along with the data to be filled in. The report number and 
the data are passed in the variable format (e.g., IC, LEN, 
DATA). The data items passed are to be displayed in fields 
defined as unprotected. The Output Utility will generate any 
SBA and TABS needed and put an insert cursor order after the 
first tab. Any field shorter than its length on the screen 
will be padded with nulls on the right; any unprotected field 
not passed data will be skipped. 
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OUTPUT FORMAT TABLE ENTRY: 


CSECT 

REPORT NUM=51, LINES=5 

LINE NUM=01, ITEMS=3 

ITEM CODE=255, FROM=1,TO=6, DATA=*}s4 , COMM=ERASE, WCC= (RESET, RESTORE) 
ITEM CODE=255, FROM=7, TO=12,ATT=(PRO,SKIP,HIGH,MOD) , DATA='VERB' 
ITEM CODE=255, FROM=13,TO=15,ATT=(PRO,SKIP) ,DATA='f'! 

LINE NUM=2, ITEMS=4 , REPET=6 

ITEM CODE=255,FROM=6, TO=12,ATT=(PRO,SKIP) , DATA='NAME: ! 

ITEM CODE=255,FROM=13, TO=15,ATT=YES,DATA=(X'13') INSERT CURSOR 
ITEM CODE=$1,FROM=16,TO=38 

ITEM CODE=255,FROM=39,T0=41,DATA='}', ATT= (PRO, SKIP) 

LINE NUM=03, ITEMS=3 ,REPET=6 

ITEM CODE=255, FROM=7, TO=15,ATT=(PRO,SKIP) , DATA='SALARY:' 

ITEM CODE=02, FROM=16, TO=23, ATT=NUM 

ITEM CODE=255, FROM=24, TO=26,ATT=(PRO,SKIP) , DATA='FY' 

LINE NUM=04, ITEMS=3 ,REPET=6 

ITEM CODE=255, FROM=7,TO=18,ATT=(PRO,SKIP) ,DATA='JOB TITLE:' 
ITEM CODE=03, FROM=19, TO=31,ATT=YES 

ITEM CODE=255, FROM=32,TO=34,ATT=(PRO,SKIP) ,DATA='}' 

LINE NUM=05, ITEMS=3 , REPET=6 

ITEM CODE=255, FROM=7,TO=15,ATT=(PRO,SKIP) , DATA='PHONE #:' 

ITEM CODE=04, FROM=16,TO=29,ATT=YES 

ITEM CODE=255, FROM=30,T0=32,ATT=(PRO,SKIP) , DATA='}' 

Sample 3270 Screen Generation. (Sheet 1 of 3) 
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Figure 29. Sample 3270 Screen Generation. (Sheet 2 of 3) 


FROM OUTPUT UTILITY (including OUT327@) 


RESET 
RES TORE 


NdtfI 


VL/TE/ZT 6LO 


rot 


DISPLAY AT 3270: 


on 
>) 


: CO er el | LLL | ba LT cree if 1 a: 

molt ELL | eatole| Patefoe bb EY ETT TTT TTT Tet TT 

6 PEEP HERSERET EERE PECCCEEEEEL EEE EEE 

met TTT TTT TTT TTT TTT 

ee 

230 a CECE EEE Re 
eae PECCEEEEE PEELE 

60 ELE ETT TTT TTT TTT TTT 

0 Hit PCH TLE 

2) AE 


Figure 29. Sample 3270 Screen Generation. (Sheet 3 of 3) 


The command, WCC, and SBA sequence will be inserted by the 
Output Utility. The default command for all X'56' VMI output 
messages is a Write command. The default WCC is restore key- 
board and not reset modified data tags. The default SBA 
sequence is an SBA to zero. In order to erase all unprotected 
data and reset modified data tags, when filling in a screen 
format, the ERASE operand may be specified in the REPORT 

macro of the OFT entry. Since an EAU command cannot contain 
data, an erase unprotected to address order will be used 
instead. 


If the application desires other than the default command, 

WCC and SBA sequence (or ERASE=YES), he should send the com- 
mand sequence in an item code 251 item, passed to the Output 
Utility in the VMI of X'56' message. The 251 ITEM does not 
get coded in the report. If the data following ITEM CODE 251 
in the message text contains 1 byte that byte will become the 
command; if it contains 2 bytes those bytes will become the 
command, WCC sequence; if it contains 5 bytes those bytes will 
become the command, WCC, SBA sequence. 


If an erase all unprotected (EAU) command is placed ina 25l 
item and there is also a data item passed, an Erase Unprotected 
to Address order will be used to erase the unprotected fields. 


Figure 30 illustrates an existing screen format, a message to 
OUTPUT, and the resulting message to the terminal. 


Modifying Screen Format: 


It may be necessary for the application program to modify 
definition:‘of fields or field data (other than unprotected) 
in a format already on the screen. 


In order to facilitate this, a special 253 item has been 
added. The 253 item does not get coded in the report. When 
the application program passes the report number to the output 
utility (via a VMI of X'56') he can pass all orders or data 
needed along with a 253 item.. The contents of the item will 
be placed at the end of the output message before the ETX is 
added by the Output Utility. For example: 


Message to OUTPUT: 


Message from OUTPUT: 
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Figure 30. Filling in a 3270 Screen Format (Unprotected: Data) (Sheet 1 of 2) 
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Adding to an Existing OFT Dynamically: 


To modify an existing OFT (more than just data), the applica- 
tion passes all necessary orders and data in a special 253 
item, along with other items, in the (VMI of X'56') message. 
(The 253 ITEM does not get coded as an item in the report.) 


This special item must begin with an SBA order. The contents 
of the item will be placed at the end of the output message 
before an ETX is added by the OUTPUT Utility. 


INTERCOMM VI.1 Enhancements 


With INTERCOMM VI.1 (April 1974), a new operand was added to the 
REPORT macro to simplify specification of FROM and TO positions 
of data in ITEM macros. The optional operand DEV=3270 specifies 
that the receiving terminal is an IBM 3270 Model 2 (Remote or 
Local) and that the OUTPUT Utility is to be responsible for 
generating all hardware dependent control characters. Note 

that use of this feature results in terminal-dependent Output 
Format Table entries which must not be referenced when a mes- 
sage is destined for a terminal other than the IBM 3270. The 
Output Format Table may contain a combination of entries of 
which some specify the DEV=3270 operand on their REPORT macros. 


If DEV=3279 is specified, the FROM and TO values specified on 
subsequent ITEM macros indicate only those characters in the 
data item which occupy a hardware buffer position. That is, 
the FROM and TO may reference the actual positions ina line 
of 3279 display. Additionally, SBA sequences will be used for 
positioning to the start of a new field. LINE macros may not 
define repetitive lines (REPET=1l1, 4 or 8 not allowed). 


If DEV=327¢@ is not specified, the generation of the report will 
be exactly as it was before the DEV= operand was available. 

That is, all characters generated for a given field must be 
reflected in the FROM and TO specification, including characters 
such as SF or IC which do not occupy a 3276 buffer position. 
Positioning to a new field is done by padding with blanks. 


The following table entry illustrates an Output Format Table 
Coded with the DEV= 3270 operand. 


RPTO0060 CSECT 
RPTOO6O0 REPORT nuM=60, LINES=3,DEV=3270 
LINE NUM=1,ITEMS=3 
ITEM CODE=255,FROM=1,TO=5,ATT=(PRO,MOD), 
COMM=WRITE,WCC=RESTORE, DATA='VERB'! 
ITEM CODE=255,FROM=6,TO=6,ATT=PRO 
ITEM CODE=01,FROM=16,TO=25,ATT=YES 
LINE NUM=2,ITEMS=3 
ITEM CODE=255,FROM=9,TO=20,ATT=HIGH, 
DATA='3270 LINE 2' 
ITEM CODE=255,FROM=21,TO=21,ATT=PRO 
ITEM CODE=02,FROM=27,TO=42,ATT=YES 
LINE NUM=3,ITEMS=2 
ITEM CODE=3,FROM=42,TO=45,ATT=YES 
ITEM CODE=255,FROM=50,TO=61,ATT=PRO, 
DATA='3270 LINE 3' 
END 
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Teletype Dataspeed 40/1 and 2 (DS40) 


The Teletype Dataspeed 40 Models 1 and 2 are supported for the 
Edit and Output Utilities, as descirbed below. 


Edit Utility 


If TYPE=DS40 is coded in the DEVICE and STATION macros for the 
DS40 terminal, Edit Utility processing accepts: 


@ The Horizontal Tab (HT) xX'05' (required for input from 
formatted screens) 


@® The New Line (NL) X'15' 


as field separator characters in addition to the system separator 
character. When editing positinal data, an HT followed by a second HT 
or NL, or an NL followed by an HT indicates absence of a field. 
However, an HT following the system separator after a verb assumes 
input from a formatted screen, not absence of the first positional 
field. 


Output Utility 


If DEV=DS40 is coded in the REPORT macro, the corresponding ITEM 
macro ESC parameter allows specification of ESC sequences and other 
control characters for output report formatting. Thus, formatted 
screens with protected and unprotected fields may be defined. 


New Line as a line ending control character is automatically 
generated in Output Utility processing. This does not affect the 
current protected/unprotected status of the screen area. 


Further details on message control characters, terminal 
operation considerations, and format design considerations are 
discussed in the Operating Reference Manual, Section 5. 


NOTE: The Teletype Dataspeed 40 Model 4 terminal is IBM 3270 
hardware compatible and is supported under Intercomm as 
such. 


Leased 2780 Considerations 


If TYPE=2 (and FIRST=YES) are coded on the DEVICE macro, the 
Output Utility assumes the terminal is a leased 2780. All messages 
processed by the Output Utility will start with 'X022761'. Each line 
will end with X'1F2761' instead of a CRLF value. 
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INTERCOMM TABLES 
FOR THE UTILITIES 


Basic Tables are included on the INTERCOMM release library 

and must be modified for each installation. An asterisk in- 

dicates optional tables which may be generated individually 

at each installation according to application program require- 
CSECT 


mMents. 
SYMREL & 
MODREL 
Name Description Created by|Member Name 
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PADDTBLE' PADDTBLE 


PMIALTRP PMTALTRN 


macro 
DEVICE 
macro 
GENFTBLE PMIFILET 


PMIRCNTB 


*OUTPUT Alternate 
Format Table 


PMIDEVTB OUTPUT Device Table PMIDEVTB 


PMIFILET CHANGE/DISPLAY File 


Table 


PMIRCNTB 
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INTERCOMM TABLES 
FOR THE UTILITIES 


(Continued) 


SYMREL & 


MODREL 
Created by| Member Name 


STATION 
macro 


PMISTATB 


*CHANGE/DISPLAY Field 
Editing Pattern 


*OUTPUT Batch Report 


VERBGEN, PMIVERBS 
VERB, 

PARM, 

PMIELIN 


macros 
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VERB -- Define Edit Control Table Entry 


The VERB macro is used in conjunction with the PARM, PMIELIN and 
PMISTOP macro instructions to generate an Edit Control Table for 
processing by Intercomm's Edit Utility. When used, the VERB macro 
subordinates one or more PARM macros, and if used, one or more PMIELIN 
macros. Each VERB macro instruction defines a unique Edit Control 
Table entry. 


The form of the VERB macro instruction is as follows: 


transaction-id,hex-id, ( 36 | ; 
256 


(0° f-parm-ins Tructions} 


acy) 


acts) 
mee) 


(;RBN=vrb 000-rbn J 


ere) 


coresize 

specifies the length, in bytes, of storage required after 
editing, for the longest possible message associated with the 
transaction entry being defined. Note that the length of the 
message after editing is equal to the combined length of the 
edited fields plus the message header, and any applicable status 
bytes. Any "coresize" residue is freed. Code as a decimal 
value, 256 to 4095. The default is 256. 


FIX= 
indicates the kind of format the Edit Utility is to produce. 
Coding YES indicates that the data is to be placed in a fixed 
format. Coding NO indicates that the data is to be placed in a 
variable itemcode/length/data format. The default is NO. 
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VERB VERB 


hex-id 
provides a hexadecimal transaction identification code. Code as 
a hexadecimal value, 1 to FF. A program calling the Edit Utility 
can expect to have this code returned in the one byte MSGHVMI 
field of the message _ header, if the value coded _ for 
#-of-parm-instructions is non-zero. 


KEY= 
indicates whether the transaction format is keyword or 
positional. Coding YES indicates that it is either wholly in 
keyword transaction format, or in  positional-within-keyword 
transaction format. Coding NO indicates that it is wholly in 
positional transaction format. The default is YES. 

LINE= 


indicates whether PMIELIN macros are used within the transaction 
entry being defined. Coding YES indicates that they are used. 
Coding NO indicates that they are not used. The default is NO. 


#-o f-parm-instructions 
specifies the number of PARM instructions associated with the 
transaction entry being defined. Note that this is not 
necessarily the same as the number of PARM instructions actually 
coded. Refer to the PARM macro, REPT parameter. If the hex-id 
operand value is to be moved to MSGHVMI, a non-zero value must be 
specified for #-of-parm-instructions. 


PREONLY= 
indicates whether the message is to be processed only by the 
pre-Edit facility which converts IBM 3270 input (SBA sequences) 
into standard unedited positional format. When coded YES (if 
input is from IBM 3270, with preformated screen), the above 
statement applies. When coded NO the message is edited in the 
usual way. 


RBN= 

provides the relative block number of the VRBOOO file at which 
the corresponding transaction format entry can be located. If 
the entry being defined is to be resident, this parameter is 
meaningless. However, if the entry is to be located within the 
VRBOOO file, then the RBN value should reflect the last five 
digits of the member-name used to place the entry in the file. 
For example, if the member-name is VRB0O0006, then code RBN=6. 
Code as a decimal value, 1 to 8388607. 


transac tion-id 
provides the unique transaction character code, the verb name, 
for the transaction entry being defined. Code as a fixed length 
character string of four characters. 
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PARM -- Define Data Unit 


The PARM macro instruction is used in conjunction with the 
VERB, PMIELIN, and PMISTOP macro instructions. These four 
instructions are employed together to furnish the Edit Control 
Tables required by Intercomm's Edit utility. When employed, 
the PARM macro instruction is subordinated to a VERB macro 
instruction, and in function provides that utility on a data 
unit basis with the information it requires to process it. 


The form of the PARM macro instruction is as follows: 


char-id,itemcode,editrout-#,max-length, 


a 


7 — 


—oo en" 


char-id 
provides the character symbol to be associated with the 
data unit upon which editing is to be performed. If 
"KEY=NO" has been coded on the associated VERB instruction, 
"char-id" is used by Intercomm only for error reporting 
identification. Code as a fixed length 3-character 
String. If the IBM 3270 pre-formatted screen input is 
being used, the parameter name must be 4 hex digits. 
These identify the parameter by 3270 buffer address, 


itemcode 
provides the numerical identification to be associated 
with the data unit upon which editing is to be performed. 
If "FIXszYES" is coded on the associated VERB instruction, 
this identification is used only in processing internal to 
the Edit utility. Code as a decimal value, 0 to 254. 
Note that if the text represented by the PARM instruction 
is to be completely ignored (as might be desired for tem- 
plate screens), “itemcode" must be coded as a QO. 


editrout—# 
provides the number of the subroutine to be used to per- 
form editing upon the data unit. Note that this number 
designates the editing subroutine whose three-digit csect- 
name suffix is identical in value i.e. a code of 8 
designates subroutine EDITO08. Code as a decimal value, 
O to 255. 
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PARM Macro 


(Continued) 


max-length 
specifies the maximum permissible length, in bytes, with- 
in which the data unit, after editing, is permitted to be 
contained. Note that if "FIX=YES" is coded on the asso- 
ciated VERB instruction, “max-length" is always allocated 
regardless of actual data length. Code as a decimal 
value, O to 255. 


editflags 
provides specification and procedural information. Code 
as a fixed length bit string of 8 bits whose bit signifi- 
cation is as follows: 


Bit 0O Code 1 if the data unit is a required item with- 
in the transaction format under definition. 
Code 0 if the data unit is not a required item. 
L=3 Reserved. Code OQOO. 


4 Code 1 if the data unit is permitted to be 
present more than once within a single trans- 
action. 


Code 0 if the data unit is not permitted to be 
present more than once. 

5 Code 1 if, after editing, the data unit is al- 
ways to be contained within the length specified 
by the "max~-length" parameter. Note that if 
"FIX=YES" is specified on the associated VERB 
macro instruction this bit will default to l. 
Code 0 if the data unit is permitted to be 
assigned a variable length. 

6-7 If a given data unit exceeds the "max-length" 
Parameter value these two bits denote the action 
to be taken. 

Code 11 if no truncation is permitted. 
Code 10 if right truncation is permitted. 
Code O1 if left truncation is permitted. 
Code 00 is not meaningful. 


REPT= 
specifies to the macro processor the number of times the 
PARM macro instruction is to be generated. Note that the 
"#-of-'parm'-instructions" parameter on the associated 
VERB macro instruction must include this value. Note also 
that if the VERB instruction specifies "KEY=YES" and 
"FIX=NO", the default must be taken. [f editflags bit & 
is on, then at least one data unit is required. Code as a 
decimal value, 1 to 100. The default code is l. 
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VERBGEN Macro 


VERBGEN -- Conditionally Assemble Edit Control Table PARM Macros 


The VERBGEN macro instruction informs the internal pro- 
cessor of each PARM macro instruction that it is not to gen- 
erate the code for that instruction if it is aSsociated with 
a VERB macro instruction specifying an "RBN=" value. The 
VERBGEN macro instruction is used when creating the core- 
reSident edit control and is meaningful only when one or 
more table entries are located within the VRBOOO file. 


The form of the VERBGEN macro inStruction iS as follows: 


(blank) VERBGEN (blank) 
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PMIELIN Macro 


PMIELIN -- Designate End of Line (Positional Transaction Format) 
sameeren car SS SSS, 


The PMIELIN macro instruction is used in conjunction with 
the VERB, PARM, and PMISTOP macro instructions. These four 
instructions are used together to create edit control tables 
for INTERCOMM's Edit utility. The PMIELIN macro instruction 
is used to delineate a line only when a positional transaction 
format is under definition. The generated code - c'ssss' - 
Signifies to the utility the legitimate end of expected data 
for a given input line and functions as a tab setting to which 
a skip is made when an end-of-line character (NL or CR/LF) is 
detected as having signified a permissible premature termina- 
tion of that line. 


The form of the PMIELIN macro instruction is as follows: 


J 
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PADD -- Define Padding Character 
The PADD macro instruction supplies the EDIT Control 
Routine with the pad character to be used with each EDIT 


subroutine. 


The form of the PADD macro instruction is as follows: 


[symbol] editrout-#,pad-char — 


editrout-—# 
provides the number of the subroutine to be used to perform 
editing upon the data unit. Note that this number designates 
the editing subroutine.whose three-digit csectname suffix 
is identical in value i.e. a code of 8 designates subroutine 
EDITOO8. Code as a decimal value, 0 to 255. 


pad-char 
specifies the character that is to be generated as a pad 
character to be used with each EDIT subroutine. The 
permissable codes are BLANK, BZER, ZERO, Char. Only one may 
be selected. 


' 
specifies that a blank (X 40°) is to be generated 


BLANK - 
as a pad character. 

BZER - specifies that a binary zero (x! 00') is to be 
generated as a pad character. 

ZERO ~ specifies that a character zero (C ‘9 ') is to be 
generated as a pad character. 

Char - any user specified hexadecimal value. Code as 


a 2 digit hexadecimal value i.e. 3C. 


c 


IPN 135 9/78 
REPORT REPORT 


REPORT -- Identify Reporting Format 


The REPORT macro instruction is used in conjunction with the LINE 
and ITEM macro instructions to define a reporting format for the Output 
Utility. The REPORT macro subordinates one or more LINE macros. Each 
REPORT instruction identifies and defines a unique reporting format 
while the subordinated LINE instructions detail, line by line, the 
contents of that format. 


The form of the REPORT macro instruction is as follows: 


[symb O 1} REPORT NUM=re port -number 


( _ #-of-line-ins oie | 
1 

» MASK=] hex-mask 
0000 


IBM 3270, GTE IS 7800, and DS40 
specifications: 


Saas 3 


, DEV= { 3270 
187800 
DS40 


DEV= 

DEV=3270 signifies an IBM 3270 Model 2 or a GTE IS7800 operating 
in 3270 mode. If DEV=3270 is specified, the FROM and TO values 
on subsequent ITEM macros include only those control and/or data 
characters which occupy a hardware buffer position. That is, the 
FROM and TO may reference the actual positions in a line of 3270 
display. Additionally, an SBA sequence will be used for 
positioning to the start of a new field (attribute value). The 
LINE macros associated with this REPORT may not specify REPET=1, 
4, or 8. 


If DEV=3270 is not specified for a 3270, then all characters 
generated for a given field must be reflected in the FROM and TO 
specification, including characters such as SF or IC which do not 
occupy a 3270 buffer position. Positioning to a new field is 
done by padding with blanks. 


REPORT 
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REPORT 


DEV=1S7800 signifies that the REPORT is for a GTE IS7800 and that 
it may contain requests for blink, underlined, or inverted 


characters, 


DEV=DS40 


and double width characters. 


signifies a Teletype (Dataspeed) Model 40/1 or 2 


terminal; this specification allows coding of the ESC parameter 
on the ITEM macro. 


ERASE= 


specifies whether or not an ERASE-unprotected-to-address order 
will be generated for messages processed by the Output Utility 
with header field MSGHVMI=X'56'. YES causes the message to 
contain a WRITE command, WCC of restore the key-board and reset 
modified data tags, and the ERASE order. The default is NO. 


LINES= 
specifies 


the number of LINE macro instructions used in the 


format being defined. Code as a decimal value, 1 to 255. The 
default code is l. 


MASK= 


specifies by its bit configuration the terminal recipient class 
to which the report belongs. Since all classification is founded 
upon the relation noted below, each STATION macro MASK parameter 
must be co-ordinatively set in conjunction with this REPORT macro 
MASK parameter. The code is to be thought of as a 32 bit string 
written as a one to four hexadecimal character string with all 
codes not four characters being right adjusted then left padded 


with zeros. 


0000 - 


8000 - 


The following codes should be noted: 


signifies that the associated report belongs to no 
unique terminal recipient class and is free to be 
received by any terminal within the system. This is 
the default code. 


represents a class of error reports for which 
Intercomm's OUTPUT Utility will, in addition to 
forwarding the report, construct and attach a 
one-line prefix consisting (if printable) of the low 
order sending subsystem code followed by the report 
number. 


The classification relation is as follows: If the STATION macro 


MASK code 


is ANDed into the REPORT macro MASK code and the 


latter's code remains unchanged, then the terminal assigned the 
former is considered eligible to receive the report assigned the 


latter. 


C-2 


REPORT 


NUM= 
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REPORT 


provides the logical number assigned to identify the report being 


de fined. 


Code as a decimal value, 51 to 32767. Codes 1 to 50 


are reserved. 


NOTE: 


symbol 


If the reporting format is to be placed on disk via a 
PMILOAD execution then this number must be _ embedded 
within the five-digit suffix of the format's member 
name. For example report number 62 provided with a 
member name of RPTO0062 will be accessed via RBN 62. 


If a label is provided it should not exceed seven characters in 


length. 


If its length exceeds seven characters, only the first 


seven will be recognized. 


c-3 
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LINE Macro 


LINE -- Define Line 


The LINE macro instruction is used in conjunction with the 
REPORT and ITEM macro instructions. These three macro instruc- 
tions are employed together to define prescribed reporting for- 
mats for INTERCOMM's Output utility. When employed, the LINE 
macro instruction subordinates one or more ITEM macro instruc- 
tions, and in function claims its domain over all those ITEM 
instructions associated with it. In principle, the LINE in- 
struction defines a unique line within the reporting format 
under definition while the subordinated ITEM instructions 
detail segment by segment the constitution of that line. 


The form of the LINE macro instruction is as follows: 


NUM= anes 
i 
, LTEMS= ‘ieee miele: 
ul 
, 


0 


— Se eer weer 


NUM= 
assignes a logical number to the line. This number must 
be one unit higher in value than that assigned to the 
preceding LINE macro instruction within the reporting 
format under definition. If there are no preceding LINE 
instructions this value must be l. "“line-number" is to 
be coded as a decimal value, 1 to 255. The default code 
is l. 

ITEMS= 


specifies the number of ITEM macro instructions that are 
to be associated with the LINE macro instruction. The 
default code is 1. Code as a decimal value, 0 to 24. A 
code of 0 will provide one blank line. 


NOTE: The maximum number of coded ITEMS per line is 24 
for 3270 or IS7800 users who have coded DEV=3270 or IS7800 
in the REPORT macro becauSe aS Many as three ITEMS can be 
generated for each coded ITEM. For all non 3270 users, 


the maximum ITEMs per line is 72. 


C 
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REPET= 
provices the line control code for the line under 
definition. The permissable character codes are 
0,1,4,5,6,8. Only one may be selected. 


O - designates a non-repetitive line. 

1 - designates a repetitive line. 

2- is no longer in use. 

3 - is no longer in use. 

4 - designates a repetitive line and requests that 
the line's constant data is always to be included 
in the report even if no variable data exists for 
the line. 

5 - designates a non-repetitive line and is to be used 


only with respect to segmented messages. It 
specifies that the line is to be included in the 
report only when a message whose MSGHVMI field is 
X'51' is received. This does not apply to messages 
whose MSGHVMI field is X'5C'. 

6 - designates a non-repetitive line and requests that 
the line's constant data is always to be included 
in the report even if no variable data exists for 
the line. 

8 - designates a repetitive line and requests that if a 
buffer or screen overflow occurs, the preceeding non- 
repetitive line(s) already contained within the buffer 
Or screen are to be repeated within the subsequent 
buffer or screen. The default code is OQ. 


Repetitive lines may not be used in a table entry where 
the REPORT macro specifies DEV=3270 or IS7800. 
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ITEM -- Define Line Segment 


The ITEM macro instruction is used in conjunction with the REPORT 
and LINE macro instructions to define reporting formats for Intercomm's 
Output Utility. The ITEM macro is subordinate to a LINE macro. Its 
primary function is to define a segment of the line and assign a unit 
of text for it. The ITEM instruction directly or indirectly designates 
a set of characters that ultimately become part of the output character 
stream; the ITEM macro instruction may therefore have a _ secondary 
function of inserting mnon-texted (for example, device control) 
characters into that stream. Refer particularly to the CODE parameter. 


The forms of the ITEM macro instruction is as follows: 


(symbo 1] ITEM FROM=co lumn, TO=co lumn, CODE=itemcode 


, DATA= | 'constant-data' 
(con-el, con-el, e 5) 
IBM 3270 and GTE 1IS7800 specifications: 


,COMM= | X'nn' ,»WCC= { X‘nn' : 
write (subparameters) 


ERASE 


,ATT=(X'nn' 
YES 
(subparameters) 


GTE 187800 specification: 
(> ORDER=SC | 


Teletype Model 40/1 or 2 specification: 


, ESC= | esc-code 
(esccodel,esccode2,...,) 


(for IBM 3270 and GTE IS7800 only) 

Use of this parameter causes an IBM 3270 field prefix to be 
generated consisting of a SF order and an attribute byte. If 
DEV=3270 or IS7800 has been specified on the REPORT macro, the 
FROM and TO parameters on the ITEM macro refer to the screen 
positions occupied by the attribute byte and the data; if 
DEV=3270 or 1S7800 has not been specified, then the FROM and TO 
parameters must refer to the relative 3270 buffer addresses 
(relative to the beginning of the line), including the SF, the 
attribute byte and the data. 


ATT= 
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Designates that an SF order and an attribute byte are to be gen- 
erated preceding the DATA item defined. 


X'nn' - specifies hexadecimal attribute byte 
YES indicates the attribute byte is generated for all default 
attributes: unprotected, no autoskip, alphanumeric, nondetec- 


tible, nonmodified. 


Subparameters is a keyword list to indicate attributes. 


PRO protected 

SKIP autoskip 
NUM numeric 

PEN normal intensity, detectable 

HIGH high intensity, detectable 

NON non-display ,non-print ,non-detectable 

MOD field data tagged as modified 


Additionally, if DEV=1IS7800 is specified on the REPORT macro, 
then the following subparameters are allowed: 


BLNK blink 

INVT inverted characters 

DW double width characters 
ULNE under line 


The subparameters are not positional. If any subparameter is 
omitted, the default is taken in the corresponding order of the 
YES attributes. All 1S7800 subparameters must be specified in 
order to be used. For valid combination of 1IS7800 ATTs and IBM 
3270 ATTs see the 1S7800 manual. If the ATT operand is omitted, 
no SF and ATT bytes are generated. 


specifies the numerical identification associated with the set of 
characters that is to be placed in the output stream. This set 
of characters may originate from within the text of the message 
initiating the report, or the reporting format table itself. If 
the set of characters is to be extracted from the message text, 
code the associated user-assigned itemcode, 1 to 249. If, how- 
ever, the set of characters is to be extracted from the reporting 
format itself, the code (250 to 255) is to specify the type of 
constant data that is being extracted. 


250-253 —- Reserved codes. Code 252 is used by the Page facil- 
ity for the page number. 


254 - specifies that the constant(s) supplied by the DATA 
parameter are one or more device control characters. 


255 - specifies that the constant(s) supplied by the DATA 
parameter are one or more text characters. 
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When DEV=3270, codes 250, 251, 253, 254 and 255 require coding of 
either DATA or ATT. For non-3270 devices, codes 254 and 255 require 
the DATA parameter. 


NOTE: The distinction to be made between codes 254 and 255 is 
that the constant data denoted by a 254 code is not 
considered to occupy any space within the device's 
buffer. However, because the FROM and TO parameters must 
always be coded to position characters relative to 
others, a line containing a 254 constant is internally 
expanded by the length of that constant without altering 
the relative positions of the printed text. The FROM and 
TO parameters may therefore specify 'column' positions 
not actually available on the device. For example, if, 
on setting up an 80Q-character line, a 6-letter 
non-constant text unit is to be placed in positions 72 
through 77 and three control characters are then to be 
sent before an asterisk is inserted at position 80, the 
pertinent successive specifications would be as follows: 


(CODE=user-assigned itemcode) — FROM=72,TO=77 then 
(CODE=254) - FROM=78,TO=80;then 
(CODE=255) - FROM=83,TO=83. 


COMM= 
designates a command to prefix the message text created for an 
IBM 3270 terminal. X'nn' specifies the actual command; WRITE 
specifies the Write Command; ERASE specifies the Write Erase 
Command. ERASE is the default. This parameter is used in 
conjunction with the WCC parameter. 


DATA= 
specifies constants to be generated in the output. stream. 
Constant-data is coded as a character string. Con-el specifies 
any expression that can be used as an Assembler DC instruction 
operand, such as, DATA=(4XL1'15',C'LINE''S OF DATA’). This 
parameter is meaningful only if a code of 254 or 255 has been 
assigned to the CODE parameter. 


ESC= 
specifies the control character to be prefixed with an escape 
(ESC) character (X'27'), or, a special control character. 


Code as a single code or list of codes. Valid codes are any 
single code valid after an escape character, e.g., H,X,R, etc.; 
or one of the following special codes: 


ITEM 


FROM 


DC4 
BEL 
HT 
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Meaning 


form-feed 
start print 
stop print 
bell 
horizontal tab 


There is no default code. This parameter has meaning only when 


DEV=DS40 


is coded on the corresponding REPORT macro. The 


parameter may be coded alone when CODE=254, or in addition to 


initial 
See the 


value data (CODE=255), or with a data field code number. 
Switched Teletype (Dataspeed) Model 40/1-2 support in the 


BTAM Terminal Support Guide, for format design considerations. 


specifie 


s, by character column relative to 1, the location within 


the line of the left-most boundary of the line segment being 


defined, 


i.e., the position at and from which character insertion 


is to begin. The code, in value, must be equal to or less than 


that ass 


igned to the TO parameter. Code as a decimal value, 1 to 


255. See note under the CODE parameter. 


ORDER=SC 


TO 


WCC 


For GTE 


IS7800 only. Designates an SC order if an attribute byte 


ATT=X'nn' is specified. Requires DEV=IS7800 to be coded on the 
REPORT macro. (Does not apply if DEV=3270 is coded on the REPORT 


macro. ) 


specifies, by character column relative to 1, the location within 
the line of the right-most boundary of the line segment under 


definiti 
inserted 


on, i.e., the position at which a character can be 
but beyond which no overflow characters are to be 


permitted. 


NOTE: 


If there is insufficient room to include all data within 
the segment of the line assigned to it, the Output 
utility will generate a sufficient number of lines of the 
same format to contain it. The code, in value, must be 
equal to or greater than that assigned to the FROM 
parameter. Code as a decimal value, 1 to 255. See note 
under CODE parameter. 


designates a WCC to prefix the message text created for an IBM 
3270 terminal. X'nn' specifies the actual WCC; subparameters are 
(linesize, PRINT, ALARM, RESTORE, RESET) and specify WCC 


options. 
omitted, 


The subparameters are not positional. If they are 
a default value is taken. The default value of the 


subparameter is its opposite (that is, default for PRINT is NO 


PRINT). 
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PMIALTRN--Specify Alternate Reporting Formats 


The PMIALTRN macro is used to specify to Intercomm's Output 
Utility the alternative reporting formats that are to be employed when 
an alternate destination terminal is a device different in kind from 
the primary destination terminal. 


The form of the PMIALTRN macro is as follows: 


{symbol} PMIALTRN eae, devcode, (alt-format-—#,alt- 


devocde ;,alt-format-#,al t-devcode } er, 


format—# 
specifies the reporting format identification for which one or 
more alternative reporting formats are being supplied by the 
alt-format-#" parameter. Code as a decimal value, 1 to 32767. 
Refer to the REPORT macro, NUM parameter. 


devocde 
specifies the type code of the device directly associated with 
the reporting format designated by the format-# parameter. Code 
as a hexadecimal value, 0 to F. Refer to the DEVICE macro, TYPE 
parameter. 


alt-format-# 
specifies the identification of an altervative reporting format 
that is to be used in place of format-# when the destination 
terminal is a device of the type designated by the immediately 
following "alt-devcode" parameter. Code as a decimal value, 1 to 
32767. 


alt-devcode 
specifies the type code of the device to be associated with the 
reporting format designated by the immediately preceding 
"alt=format-#" parameter. Code as a hexadecimal value, 0 to F. 


NOTE: Alternate report formats cannot be used from terminals 
whose DEVICE macro specify MMV designation (IBM 3270, 
Dataspeed 40, etc.) for the TYPE parameter. 
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FDHDR ~- Define Change-Display Information Table 


The FDHDR macro instruction is used in conjunction with the 
FDETL macro instruction. These two macro instructions are 
employed together to furnish the tables required by INTER- 
COMM's Change and Display utilities. When employed, the 
FDHDR macro instruction subordinates the FDETL macro instruc- 
tion, and provides information unique to the data structure 
partially or wholly detailed by its associated set of FDETL 
macros. 


The form of the FDHDR macro instruction is as follows: 


ddname 
FIELDS=#-of-'fdetl'-instructions, 


NAME= i Saati ; 


RPTNO=format-number ae wae? 
¢) 


sewn oe een 


o J 


NAME= 
provides the unique name that will identify the table 
under generation. This name, coded as a variable length 
character string of 1 to 8 characters, will be either an 
identifier located within the CHNGTB table or a ddname of 
a file. 


FIELDS= 
provides the number of associated FDETL macro instruc- 
tions used to detail some or all of the fields within the 
data structure. Code as a decimal value, 1 to 4095. 


RPTNO= 
supplies the format number that will, by default, be used 
to format selectively or otherwise, data found within the 
fields specified within the table under definition. 
"format-number" is to be coded as a decimal value, 51 to 
32767. (Refer to the REPORT macro "NUM=" parameter.) 
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KEY RT= 

provides the numerical identification assigned to that 
routine whose function it is to ultimately provide a 
valid key for file data retrieval. If the "NAME=chngtbl- 
identifier" prescription is used, this parameter is not 
meaningful. If the table under generation is being ap- 
Rlied to the record format of either a BDAM or ISAM file, 
it is recommended that for BDAM a 2 be coded, and for ISAM 
a 0 be coded. "Number-id" is to be coded as a decimal 
value, 0 to 255. The default code is 0. Note that user 
coded routines are numerically identified via the KEYTABLE 
table. 


REPSZ= 
provides the length, in bytes, of the repetitive substruc- 
ture if one is present. Note that the total length of all 
fields described by the associated FDETL macros specifying 
"FLD=REPET" will never exceed the value of this code. 
Code as a decimal value, 0 to 4095. The default code of O 
Signifies that no substructure is present. 


IPN:093 4/76 


‘“FDETL Macro 


FDETL -- Define Data Structure Field 


The FDETL macro instruction is used in conjunction with the 
FDHDR macro instruction. These two instructions are employed 
together to furnish the tables required by INTERCOMM's Change 
and Display utilities. When employed, the FDETL macro in- 
struction is subordinated to a FDHDR macro instruction and 
functions to provide on a field basis, the following five 
classes of information 


, specificative information. 

: logically associative information. 

- data descriptive information. 

- procedural information if the data contained within 
the field is to be CHANGE'd. 

- procedural information if the data contained within 
the field is to be DISPLAY'ed. 


The form of the FDETL macro instruction is as follows: 


[ symbol] FDETL specificative parameters: 


[OFSET=byte-offset,]LEN=length, 


FLD= f HDR ; 
REPET 


logically associative parameters: 


NAME=field-id,CODE=itemcode 


metre y|| (re 


data descriptive parameter: 


,F RMAT= [BIN 
PACK 
CHAR 


"'Change' utility parameters: 


,CHNG= } YES(||,VRY=)} YES 
NO NO 


continued 
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. (Continued) 
continued 


"Change' and 'Display 
parameters: 


T,PADD= [ RIGHT »PDCHR= | BLANK 
LEFT ZERO 


"Display' utility parameters: 


[canbe EDIT 
NO J . 
,EDIT=f pattern-id, [,TRuNc= fRicHtT 
DATE i ed 
DOLLAR 
NUMBER 


OFSET= 
specifies the displacement, in bytes, from data structure 
orgin to the beginning of the field. If, on the assoc- 
iated FDHDR macro instruction, the "NAME=ddname" para- 
meter description is used, data structure origin will 
be record origin. If "NAME=chngtb=identifier" is used, 
data structure origin will be the first byte immediately 
following the 12-byte control block. If the field is 
embedded within a repetitive substructure "byte-offset" 
is to be measured to the first occurrence of the field, 
Code as a decimal value, 0 to 32767. This parameter may 
be omitted if the field is contiguous to, and directly 
follows, the field defined by the prior FDETL macro. 


LEN= 
Specifies the length, in bytes, of the field under speci- 
fication. If "FRMAT=BIN" is specified, code as a decimal 
value within the range 1 to 4. If "FRMAT=PACK", 1 to 16; 
if "FRMAT=CHAR", 1 to 255. 


FLD= 
specifies whether the field is located within the fixed 
portion of the data structure or, if one is used, within 
the repetitive portion of the data structure. Code HDR 
for the fixed portion, REPET for the repetitive portion. 
The default code is HDR. 


NAME= 
provides the character identification for the field. 
Code as a 1 to 5 character string. (Note that this is 
the name that is to be supplied on the FDN keyword of 
INTERCOMM's 'CHNG' transaction.) 


CODE= 
provides the numerical identification for the field. Note 
that this itemcode becomes the agent through which data 
contained within the field is ultimately assigned a 
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(Continued) 


location within any report. Code as a decimal value, 
1 to 249. (Refer to the ITEM macro "CODE=" parameter.) 


KEY= 
denotes whether or not the field is, in whole or in part, 
the key of a record. If "NAME=chngtbl-identifier" has 
been specified on the associated FDHDR macro instruction, 
this parameter is not meaningful. If "NAME=ddname" has 
instead been specified and the associated file uses an 
embedded key, and if, furthermore, that key incorporates 
the field under consideration, YES must be coded. The 
default code is NO. Note that "FLD=HDR" must also be 
coded. (Note further that the data supplied via the KEY 
keyword of both INTERCOMM's CHNG and DSPL request messages 
will accordingly be wholly or partially compared against 
this field.) 


SUBKY= 
denotes whether or not the field is, in whole or in part, 
the INTERCOMM subkey of a record. If "NAME-chngtbl-identi- 
fier" has been specified on the associated FDHDR macro 
instruction, this parameter is not meaningful. If "NAME= 
ddname" has instead been specified and the associated file's 
record format contains a repetitive substructure, and if, 
furthermore, the INTERCOMM subkey incorporates the field 
under consideration, YES must be coded. The default code 
is NO. Note that "FLD=REPET" must also be coded. (Note 
further that the data supplied via the SKY keyword of 
INTERCOMM's CHNG request message will accordingly be wholly 
or partially compared against this field.) 


FRMAT= 
describes the kind of data that is to be expected within 
the field. Code BIN for binary data, PACK for packed 
decimal data, or CHAR for character data. The default 
code is CHAR. . 


CHNG= : 
indicates whether or not it is permissable for the field 
to be altered by a CHNG request. Used only by INTERCOMM's 
Change utility, this parameter is meaningful only if 
"NAME=ddname" has been specified on the associated FDHDR 
macro. Code NO if such changing is not permitted. Code 
YES if it is. The default code is YES. 


VRY= 
indicates whether or not the field must be verified before 
it is permitted to be changed. Used only by INTERCOMM's 
Change utility, this parameter, is meaningful only if 
Se "NAME=ddname" has been specified on the associated FDHDR 
! Macro. Code NO for verification not required. Code YES 
for verification required. The default code is YES. 
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PADD= 
provides a request for either left or right padding. The 
absence of this parameter indicates the absence of any re- 
quest. In this particular instance the following will oc- 
cur: If, after the calculation of the maximum number of 
characters required for the displaying of the whole field 
(a function of field length, data type, and edit charac- 
ters), it is found that the data (stripped of leading 
blanks or zeros though including editing characters) 
possesses a lesser length, this lesser length will be the 
data unit considered expected by the outputting format 
through which this field is to be DISPLAY'ed. The 
presence of this parameter with either of the key-codes 
LEFT or RIGHT, indicates the presence of a request. In 
this instance, data of lesser length is expanded to the 
maximum length. A code of RIGHT’.1s regarded as a request 
to first left-justify the data, then pad on the right. A 
code of LEFT is regarded as a request to first right- 
justify the data, then pad on the left. Note that the 
"PDCHR=" parameter must be coded to provide the padding 
character. 


PDCHR= 
specifies which one of two characters (blank or zero) is 
to be used when the padding function is requested. This 
Parameter must be coded if the "PADD=" parameter is used. 
Code BLANK for a blank pad character, ZERO for a zero 
character. 


CHAR= 
indicates whether or not editing is to be performed upon 
a character field that is expected to contain solely 
numerical characters. This parameter is meaningless un- 
less “FRMAT=CHAR" has been coded. If such editing is 
requested, code EDIT and assign the appropriate "pattern 
number" to the "EDIT=" parameter; if such editing is not 
requested, code NO. The default code is NO. 


EDIT= 
provides the editing pattern identification denoting the 
pattern to be used to edit the data before DISPLAY'ing it. 
The code assigned to this parameter must be identical to 
that assigned to the "NUMBER=" parameter of the PATRN 
Macro instruction that supplies the editing pattern. Code 
"Dattern-id", DATE, DOLLAR, NUMBER accordingly. The 
default code is NUMBER. 
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Cc TRUN C= 


provides a request for either left or right truncation. 
The absence of this parameter indicates the absence of 
any request. The presence of this parameter indicates the 
presence of a request; however, such will be honored only 
wnen the "“MAXSIZE=" parameter on the associated PATRN 
INacro is not zero. Refer to "EDIT=", Data longer than 
the value assigned to "MAXSIZE=" may be truncated either 
on the left or right and truncation will always be to 
"“MAXSIZE=", Code RIGHT for right truncation, LEFT for 
left truncation. Note that this parameter applies only 
to data that is to be edited. 
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GENFTBLE -- Define File 


The GENFTBLE macro instruction is used to create the 
PMIFILET table entries that furnish certain INTERCOMM 
Subsystems with the file information they require. 


The form of the GENFTBLE macro instruction is as follows: 


[symbol] GENFTBLE FNAME=ddname, 
TYPE=| BDAM | ,BLKSIZE=blksize 
ISAM 
SAM 


[, DESNUM='dés000'-file-rbn| 


FNAME= 
provides the ddname of the file under specifications. Code 
as a character string of 1 to 8 characters in length. Any 
code not eight characters will be padded on the right to 
eight characters. 


TYPE= 
specifies the type of file under specification. Code one 
of the following symbols: 


BDAM - if the file is a BDAM file. 
ISAM - if the file is an ISAM file. 
SAM - if the file is either a BSAM or QSAM file. 


There is no default code. 


BLKSIZE= 
specifies, in bytes, the maximum length of the physical 
blocks of the file under specification. Code as a 
decimal value, 1 to 215-1. 


DESNUM= 
specifies the RBN value of the data structure description 
entry within the DESOOO file that is to be used in the 
CHANGE'ing and DISPLAY'ing of the file under definition. 
This value is to be one less than the value of the last 
five digits of the member-name used to place the entry 
in the file, e.g., if the member-name is DES00013, code 
DESNUM=12. Code as a decimal value, O to 223-1. 


IPN:093 4/76 


PATRN Macro 


PATRN -- Specify Edit Instruction Pattern 


The PATRN macro instruction is used in conjunction with the 
FDETL macro instruction "EDIT=" parameter. It is employed only 
when this parameter is utilized and serves to provide the edit- 
ing pattern for the EDIT instruction performed upon all fields 
so associated with it. 


The form of the PATRN macro instruction is as follows: 


DATE 

eouee 

NUMERIC 
PATTRN= (user-pattern) 

DATE 


PATRN NUMBER= ereiag : 


DOLLAR 


NUMERIC 
,FLOAT= fcharacter 
blank 


an (gna tenseel 
0 


symbol 
code any symbol valid in the Assembler language. This 


symbol must be coded. 


NUMBER= 
specifies the identification of the pattern under defini- 
tion. If one of the three keywords, DATE, DOLLAR, NUMERIC 
has been specified on the "PATTRN=" parameter, the identi- 
cal keyword must be assigned to this parameter. If none 
of these keywords have been employed, specify a decimal 
value, 1 to 3, 5 to 7, 9 to 15. Codes 0, 4, and 8 are 
reserved. 


PATTRN= . 
specifies the editing pattern under definition. If a 
standard date, dollar, or numeric pattern is desired, code 
DATE, DOLLAR, or NUMERIC accordingly. If a user-written 
pattern is under definition, it must contain a total of 
thirty-one digit-select and significance starter char- 
acters and this pattern may be any combination of digit 
select (X'20'), significance starter (X‘'21'), field 
separator (X'22'), and message characters. 
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(Continued) 
The standard DATE, DOLLAR, and NUMERIC patterns are as 
follows: 
DATE - X'40',24X'20',X'212020' ,2X'612020' 
resulting in the form: MM/DD/YY 
DOLLAR - X'40', X'20206B' ,8X'2020206B' ,X'2020214B2020' 
resulting possibly in: 
99,999,999,999,999,999,999,999,999,999.99 
NUMERIC - X'4020',9X'6B202020' ,X‘'6B202021' 


resulting possibly in: 
9,999,999,999,999,999,999,999,999,999,999 


Note: A user-written pattern must be enclosed within 
parenthesis. 


FLOAT= 
specifies the character to be inserted in front of the 
data after editing. Code as a Single character not en- 
closed within quotes. The default code is a blank 
character. 


MAXSIZE= 
specifies, in bytes, the maximum permitted post-edit 
length of a field edited by this pattern when that field's 
associated FDETL macro instruction "TRUNC=" parameter 2 


specifies either a code of LEFT or RIGHT, i.e., the length 
down to which a field is to be reduced after the editing 
operation has been performed. Code as a decimal value, 

L £06 3b. The default code is 0. A request for trunca- 
tion is meaningless when O is specified. 


